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, VS Code, and other MCP clients) 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. To reduce the filter-related query schema sent to the model, enable compact filter expressions. That section covers deployment and client-refresh requirements.

​
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

In Lightdash, go to Settings → MCP → Connect and choose your AI assistant. The setup guide uses your self-hosted URL to generate the command or configuration to copy. See the Lightdash MCP manual setup for client-specific instructions. 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