Skip to main content
Enterprise The MCP server needs a valid LIGHTDASH_LICENSE_KEY set on your instance — see enterprise features for applying the key. Without it, the MCP service is never registered and /api/v1/mcp returns an error.
Lightdash exposes a Model Context Protocol server that AI assistants (Claude, ChatGPT, Codex, Cursor, Claude Code, and any other MCP client) connect to for querying the semantic layer. Enabling it on a self-hosted instance is a one-flag change.

​
Prerequisites

  • Enterprise license — LIGHTDASH_LICENSE_KEY must be set on your instance.
  • HTTPS — MCP clients connect over HTTPS. See secure Lightdash with HTTPS if your instance is HTTP-only.

​
Enable MCP

Set the following environment variable on your Lightdash deployment:
The OAuth server is built into Lightdash, so no external OAuth configuration is needed — the authentication flow works the same way as it does on Lightdash Cloud.

​
Optional configuration

Set MCP_RUN_SQL_MAX_LIMIT to override the default row cap for the run_sql tool, tuned independently of AI Analyst. For example:
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 steps as Lightdash Cloud, using your self-hosted URL instead of a .lightdash.cloud address. See the Lightdash MCP installation guide for detailed instructions per AI assistant. For example, with Claude Code:

​
Network requirements

If your Lightdash instance sits behind a firewall or VPN, ensure the MCP client can reach it over HTTPS. See the MCP network requirements for additional domains that may need allow-listing depending on the AI assistant.

​
Troubleshooting