> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lightdash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Enable the Model Context Protocol server on a self-hosted Lightdash instance

<Info>
  <Badge icon="building-plus" color="blue" size="sm" shape="pill">Enterprise</Badge> The MCP server needs a valid `LIGHTDASH_LICENSE_KEY` set on your instance — see [enterprise features](/self-host/enterprise-features) for applying the key. Without it, the MCP service is never registered and `/api/v1/mcp` returns an error.
</Info>

Lightdash exposes a [Model Context Protocol](/agents/lightdash-mcp) 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](/self-host/customize-deployment/secure-lightdash-with-https) if your instance is HTTP-only.

## Enable MCP

Set the following environment variable on your Lightdash deployment:

```bash theme={null}
MCP_ENABLED=true
```

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

| Variable                | Description                                                                                                        |
| :---------------------- | :----------------------------------------------------------------------------------------------------------------- |
| `MCP_ENABLED`           | Enables the Lightdash Model Context Protocol (MCP) server. Requires `LIGHTDASH_LICENSE_KEY`. (default=false)       |
| `MCP_RUN_SQL_MAX_LIMIT` | Maximum number of rows the MCP `run_sql` tool can return. Falls back to `AI_COPILOT_MAX_QUERY_LIMIT`, then `1000`. |

Set `MCP_RUN_SQL_MAX_LIMIT` to override the default row cap for the `run_sql` tool, tuned independently of AI Analyst. For example:

```bash theme={null}
MCP_RUN_SQL_MAX_LIMIT=5000
```

Requests that ask for more rows are clamped to this limit.

## MCP URL format

Once enabled, the MCP endpoint is available at:

```text theme={null}
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 steps as Lightdash Cloud, using your self-hosted URL instead of a `.lightdash.cloud` address. See the [Lightdash MCP installation guide](/agents/lightdash-mcp#installation) for detailed instructions per AI assistant.

For example, with Claude Code:

```bash theme={null}
claude mcp add lightdash https://<your-lightdash-host>/api/v1/mcp -t http
```

## 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](/agents/lightdash-mcp#network-requirements) for additional domains that may need allow-listing depending on the AI assistant.

## Troubleshooting

| Symptom                               | Likely cause                                                                          |
| ------------------------------------- | ------------------------------------------------------------------------------------- |
| `/api/v1/mcp` returns an error or 404 | `MCP_ENABLED` isn't set to `true`, or `LIGHTDASH_LICENSE_KEY` is missing or invalid   |
| OAuth flow fails                      | The Lightdash instance isn't reachable from the browser performing the OAuth redirect |
| AI assistant can't connect            | The MCP URL is wrong or the instance isn't accessible over HTTPS                      |