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: 
MCP_ENABLED=true
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.

​
MCP URL format

Once enabled, the MCP endpoint is available at: 
https://<your-lightdash-host>/api/v1/mcp
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: 
claude mcp add lightdash https://<your-lightdash-host>/api/v1/mcp -t http

​
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

SymptomLikely cause
/api/v1/mcp returns an error or 404MCP_ENABLED is not set to true, or the license key is missing/invalid
OAuth flow failsEnsure your Lightdash instance is reachable from the browser performing the OAuth redirect
AI assistant can’t connectCheck that the MCP URL is correct and the instance is accessible over HTTPS