Skip to main content
Enable the Lightdash MCP server on your self-hosted instance and make its endpoint reachable by your AI clients. This page covers deployment configuration and network access; use the feature documentation for client setup, authentication, tools, and permissions.

​
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 backend, then restart it:
Lightdash includes the OAuth server; you don’t need a separate OAuth service. Organization administrators can still turn MCP access off, even when MCP_ENABLED=true.

​
Optional configuration

run_metric_query has no separate MCP variable — its row cap is AI_COPILOT_MAX_QUERY_LIMIT (default 5000), the same instance-wide setting that limits AI agent queries (see AI agent environment variables). It isn’t configurable per organization, and a requested limit above the cap is clamped without the response saying so. 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

Follow Connect a client to generate configuration using your instance’s URL. For headless integrations, see custom integrations.

​
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. The client needs /api/v1/mcp, the OAuth endpoints under /api/v1/oauth/, and the /.well-known/oauth-* discovery paths. Some clients connect from their vendor’s cloud rather than from the user’s machine, so an instance that’s only reachable on your internal network works from one client and fails from another. For those clients, allow the vendor’s published outbound IP ranges to reach these paths. Allow more than GET: Claude’s cloud calls POST /api/v1/oauth/token and POST /api/v1/oauth/register, and it needs POST and GET (it opens an SSE stream) on /api/v1/mcp itself. A GET-only or exact-path allowlist rule lets OAuth discovery pass but leaves the connection stuck after you click Continue connecting in Claude. To check that the endpoint is reachable from a given network, run:
A reachable instance returns 401 Unauthorized with a WWW-Authenticate header pointing at your SITE_URL. If that URL isn’t the public HTTPS address of your instance, OAuth discovery fails. Also check discovery directly:
Its issuer and token_endpoint should both be your instance’s public HTTPS address (SITE_URL), not an internal hostname.

​
Outbound egress for OAuth client ID metadata documents

Lightdash 2.580.0 and later accepts OAuth client ID metadata documents as a way for MCP clients to identify themselves, instead of registering a client first. Claude uses this: it presents an https URL as its client_id, for example https://claude.ai/oauth/mcp-oauth-client-metadata. When a user opens the authorization page for that client, the Lightdash backend fetches the document at that URL itself, over HTTPS, with no redirects and a 5-second timeout — so your backend pods need direct outbound HTTPS access to claude.ai, not routed through a proxy that blocks it. If that fetch fails, the authorization page returns 400 Invalid client_id or redirect_uri instead of the consent page.
Versions 2.580.0–2.589.3 reject client ID metadata documents that advertise extra grant types, which Claude’s document does — you need 2.589.4 or later.

​
Troubleshooting