Skip to main content
🛠 This page is for engineering teams self-hosting their own Lightdash instance. If you want to use MCP with Lightdash Cloud, go to the Lightdash MCP guide.
🔑 Enterprise feature — MCP on self-hosted instances requires a valid Enterprise License Key. Without an active license, the MCP service will not be registered and the /api/v1/mcp endpoint will return an error.

​
Prerequisites

  • A self-hosted Lightdash instance
  • A valid LIGHTDASH_LICENSE_KEY configured (setup guide)

​
Enable MCP

Set the following environment variable on your Lightdash deployment:
No additional services or external OAuth configuration is needed — the OAuth server is built into Lightdash, so the authentication flow works the same as Lightdash Cloud once MCP is enabled.

​
Optional configuration

Set the variable on your deployment to override the default cap. For example, to allow up to 5000 rows per run_sql call:
Requests that ask for more rows are clamped to this limit.

​
MCP URL format

Once enabled, the MCP endpoint is available at:
Replace <your-lightdash-host> with your instance’s domain (e.g. lightdash.yourcompany.com).

​
Connect an AI assistant

Follow the same setup steps as Lightdash Cloud, using your self-hosted URL instead of a .lightdash.cloud address. See the Lightdash MCP installation guide for detailed instructions for each AI assistant (Claude, ChatGPT, Codex, Cursor, Claude Code). For example, with Claude Code:

​
Network requirements

If your Lightdash instance is behind a firewall or VPN, ensure the MCP client can reach your Lightdash host over HTTPS. See the network requirements section for additional domains that may need to be allowlisted depending on your AI assistant.

​
Troubleshooting