> ## 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.

# Configure MCP for self-hosted Lightdash

> Enable the Model Context Protocol (MCP) integration on your self-hosted Lightdash instance.

<Note>
  🛠 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](/references/integrations/lightdash-mcp) guide.
</Note>

<Warning>
  🔑 **Enterprise feature** — MCP on self-hosted instances requires a valid [Enterprise License Key](/self-host/customize-deployment/enterprise-license-keys). Without an active license, the MCP service will not be registered and the `/api/v1/mcp` endpoint will return an error.
</Warning>

## Prerequisites

* A self-hosted Lightdash instance
* A valid `LIGHTDASH_LICENSE_KEY` configured ([setup guide](/self-host/customize-deployment/enterprise-license-keys))

## Enable MCP

Set the following environment variable on your Lightdash deployment:

```bash theme={null}
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.

## Optional configuration

| Variable                | Description                                                                                                                      |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `MCP_RUN_SQL_MAX_LIMIT` | Maximum number of rows the MCP `run_sql` tool can return per query. Defaults to 1000. Tune this independently of the AI Analyst. |

Set the variable on your deployment to override the default cap. For example, to allow up to 5000 rows per `run_sql` call:

```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:

```
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](/references/integrations/lightdash-mcp#installation) for detailed instructions for each AI assistant (Claude, ChatGPT, Codex, Cursor, Claude Code).

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 is behind a firewall or VPN, ensure the MCP client can reach your Lightdash host over HTTPS. See the [network requirements](/references/integrations/lightdash-mcp#network-requirements) section for additional domains that may need to be allowlisted depending on your AI assistant.

## Troubleshooting

| Symptom                               | Likely cause                                                                               |
| ------------------------------------- | ------------------------------------------------------------------------------------------ |
| `/api/v1/mcp` returns an error or 404 | `MCP_ENABLED` is not set to `true`, or the license key is missing/invalid                  |
| OAuth flow fails                      | Ensure your Lightdash instance is reachable from the browser performing the OAuth redirect |
| AI assistant can't connect            | Check that the MCP URL is correct and the instance is accessible over HTTPS                |