Lightdash MCP server

​

Connect a client

​

Manual setup

​

Find your instance name

​

Claude.ai and Claude Desktop

​

ChatGPT

​

Claude Code

claude mcp add --transport http lightdash 'https://<your_instance_name>.lightdash.cloud/api/v1/mcp'

​

Codex

codex mcp add lightdash --url 'https://<your_instance_name>.lightdash.cloud/api/v1/mcp'
codex mcp login lightdash

​

Cursor

{
  "mcpServers": {
    "lightdash": {
      "url": "https://<your_instance_name>.lightdash.cloud/api/v1/mcp"
    }
  }
}

​

VS Code

{
  "servers": {
    "lightdash": {
      "type": "http",
      "url": "https://<your_instance_name>.lightdash.cloud/api/v1/mcp"
    }
  }
}

​

Custom integrations

• Transport: Lightdash MCP exposes a Streamable HTTP transport endpoint at https://<your_instance_name>.lightdash.cloud/api/v1/mcp
• Debugging: Use @modelcontextprotocol/inspector to inspect and debug the MCP connection
• Authentication: For interactive setups use OAuth 2.0. For headless agents and automated workflows, you can authenticate with a Personal Access Token by passing it in the Authorization header — both Authorization: ApiKey ldpat_<redacted> and Authorization: Bearer ldpat_<redacted> are accepted on the MCP endpoint and resolve to the same PAT authentication path. The Bearer alias is accepted only on the MCP endpoint. Use Bearer when your MCP host only supports static Bearer tokens (for example, Claude managed agents and other third-party MCP hosts that don’t let you choose a custom auth scheme); use ApiKey for direct HTTP clients where you can set the scheme yourself, since it makes it explicit that the token is a Lightdash PAT. Create the token under Settings → Personal access tokens for the user whose permissions and attributes you want the integration to use. Service account tokens are also supported on plans that include them. On a self-hosted instance with DISABLE_PAT=true, the MCP endpoint refuses personal access tokens too, while OAuth and service account tokens keep working; to limit tokens to some organization roles instead, set PAT_ALLOWED_ORG_ROLES (see environment variables).
• Redirect URIs: A wildcard in a registered redirect URI matches only a port, a path, or one leftmost subdomain label, for example https://*.example.com/callback. Lightdash refuses a redirect URI that has a user name, a password or a backslash. When the agent identity feature flag is on, stricter rules apply. See OAuth with agent identity on.
• Documentation: See the MCP specification for implementation details
• Pin a project (optional): pass X-Lightdash-Project: <project-uuid> to scope the MCP session to a specific project. See details below.
• Pin an agent (optional): pass X-Lightdash-Agent: <agent-uuid> to scope the MCP session to one AI agent and its project. See details below.
• Override user attributes per request (optional): pass X-Lightdash-User-Attributes: <json> to override the authenticated user’s attributes for that request (useful for row-level security when an agent acts on behalf of different end-users). See details below.

​

OAuth with agent identity on

• Send the resource parameter set to the MCP URL, for example https://<your_instance_name>.lightdash.cloud/api/v1/mcp. Each token is for the Lightdash API or for MCP, and one audience refuses the other’s tokens. Without resource, the token is for the API, so the MCP endpoint refuses it.
• Register exact redirect URIs. Only an http loopback redirect (localhost, 127.0.0.1 or [::1]) can use a different port. Allowed schemes are https, http on a loopback host, reverse-DNS native schemes such as com.example.app, and cursor, vscode, vscode-insiders, windsurf and lightdash. Dynamic client registration refuses wildcards, except for the loopback port.
• Use PKCE with S256.
• Send the token in the Authorization header. Lightdash refuses a bearer token in the query string.

​

Pin a project with the X-Lightdash-Project header

• Tools run against the project in the header, and a tool call for any other project is refused. get_context reports this project as activeProject.
• The list_projects tool is hidden from tools/list, so the AI assistant isn’t steered toward another project.
• Access to the project is still enforced by your user, API key, or service account’s permissions — the header can’t be used to access projects the caller can’t already see.

{
  "mcpServers": {
    "lightdash-sales": {
      "url": "https://<your_instance_name>.lightdash.cloud/api/v1/mcp",
      "headers": {
        "X-Lightdash-Project": "00000000-0000-0000-0000-000000000000"
      }
    }
  }
}

curl https://<your_instance_name>.lightdash.cloud/api/v1/mcp \
  -H "Authorization: Bearer <your_token>" \
  -H "X-Lightdash-Project: 00000000-0000-0000-0000-000000000000" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

​

Pin an agent with the X-Lightdash-Agent header

• Every tool that works with project data runs with the agent’s scope, as if the AI assistant had passed the agent’s agentUuid (see Agent context). A tool call for a different agent is refused.
• The agent’s project is pinned the same way as with X-Lightdash-Project: a tool call for any other project is refused, and list_projects is hidden.
• route_agent and list_agents return only the pinned agent, and get_context reports it as activeAgent.
• The agent’s instructions are added to the server instructions that the client receives when it connects.
• Access is still enforced: the caller must have access to the agent and be able to view its project. The header can only narrow what the caller can already reach.

{
  "mcpServers": {
    "lightdash-sales-agent": {
      "url": "https://<your_instance_name>.lightdash.cloud/api/v1/mcp",
      "headers": {
        "X-Lightdash-Agent": "00000000-0000-0000-0000-000000000000"
      }
    }
  }
}

curl https://<your_instance_name>.lightdash.cloud/api/v1/mcp \
  -H "Authorization: Bearer <your_token>" \
  -H "X-Lightdash-Agent: 00000000-0000-0000-0000-000000000000" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

​

Override user attributes with the X-Lightdash-User-Attributes header

• {"user_id": "abc123"}
• {"user_id": ["abc123", "def456"]}

curl https://<your_instance_name>.lightdash.cloud/api/v1/mcp \
  -H 'Authorization: ApiKey <your_token>' \
  -H 'X-Lightdash-User-Attributes: {"user_id": "abc123"}' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

{
  "mcpServers": {
    "lightdash-agent": {
      "url": "https://<your_instance_name>.lightdash.cloud/api/v1/mcp",
      "headers": {
        "X-Lightdash-User-Attributes": "{"user_id": "abc123"}"
      }
    }
  }
}

​

Network requirements

​

Turn MCP access on or off

​

What it can do

​

Core capabilities

​

Project management

• List projects - View all accessible projects in your organization
• Set active project - Switch context between different projects (required before accessing any data). Accepts an optional tags array to filter the explores and fields visible in the session to those matching the given tags — the same tag-based filtering used by AI agents, but available directly in an MCP session without needing an agent. Useful when tags work in the Lightdash UI but you also want to scope an MCP session to a specific domain (e.g., ["sales"]).
• Get current project - Check which project is currently active

​

Data exploration

• List explores - See all available data models in the current project at a glance
• Find explores - Search for relevant data models using natural language (e.g., “customer orders”)
• Find fields - Search for specific metrics and dimensions by business terms (e.g., “total revenue”, “order date”)
• Search field values - Look up valid values for a field, useful for building filters
• Find content - Search for existing spaces, charts, and dashboards by name or description. Results include space breadcrumbs and direct links. Optionally scope the search to a single space (and its descendants) by passing a space slug.
• List content - Browse accessible content as a hierarchy. By default it returns root-level spaces; pass a space slug to list the charts, dashboards, and nested spaces directly inside that space. Use this when you want the agent to walk space → content rather than search by keyword.
• List verified content - Discover charts and dashboards that admins have marked as verified, so agents can reference trusted, canonical patterns when building new content. If you want your agent to prefer verified patterns, ask it to in your prompt (e.g. “Use verified charts as the reference for any new chart you build.”).

​

Query execution

• Run metric query - Execute queries using your semantic layer’s metrics and dimensions. Completed results include a best-effort exploreUrl so you can open the query in Lightdash to keep exploring.
• Render chart - Render a visualization (tables, bar charts, line charts, pie charts, and more) for a completed metric query result in MCP App-capable clients (e.g., Claude). Call this after a metric query finishes when you want a visual chart; the query is not re-executed. It can also render with one of the project’s custom chart types. SQL Runner results are not supported by render_chart.
• Run SQL - Execute arbitrary SQL queries directly against the project’s data warehouse. Useful for ad-hoc analysis or queries that don’t fit the explore-based model. Returns up to 500 rows by default (configurable up to 5,000). Completed results include a best-effort sqlRunnerUrl so you can open the compiled SQL in SQL Runner.
• Get query result - Poll for the result of a long-running query. run_metric_query and run_sql each wait about 50 seconds for the query to finish; if it hasn’t, the response has no exploreUrl (or sqlRunnerUrl) yet — just a queryUuid to poll. Call get_query_result with that queryUuid until the warehouse completes the query — so long queries don’t time out the session. The completed (done) response includes the same best-effort exploreUrl (or sqlRunnerUrl for run_sql queries) as a synchronously-completed call.

{
  "content": [
    { "type": "text", "text": "<CSV string with header row + data rows>" }
  ],
  "structuredContent": {
    "result": {
      "status": "done",
      "rows": [
        { "status": "completed", "n": 94, "total_amount": 2397 }
      ],
      "columns": ["status", "n", "total_amount"],
      "rowCount": 1,
      "sqlRunnerUrl": "https://<your_instance_name>.lightdash.cloud/projects/<project-uuid>/sql-runner?..."
    }
  }
}

const result = await callMcpTool('run_sql', { sql, limit });
const { rows, columns, sqlRunnerUrl } = result.structuredContent.result;
// rows: [{ status: 'completed', n: 94, ... }, ...]
// columns: ['status', 'n', 'total_amount']
// sqlRunnerUrl: shareable link to inspect/edit the SQL in SQL Runner, or null

​

Editing content

• Read content (read_content) - Fetch a chart or dashboard as JSON by slug. Call this before editing so the agent can see the current state.
• Edit content (edit_content) - Apply an RFC 6902 JSON Patch to an existing chart or dashboard, then validate and persist. Use this for surgical changes (e.g. rename a field, add a filter, swap a chart color) without rewriting the whole object.
• Create content (create_content) - Create a new chart or dashboard from a full chart-as-code or dashboard-as-code object. Returns the persisted slug and URL.

• read_content returns the document’s ordered cells (Markdown and chart-as-code charts) and its current versionUuid.
• create_content with type: "document" takes a name, slug, description, space slug, and the ordered cells.
• edit_content takes a documentEdit instead of a JSON Patch. Either replace the whole content, passing the versionUuid you read as baseVersionUuid and every cell to keep, or update the name, slug, or description on their own. If someone saved the document after you read it, the edit is rejected; read it again and retry. Each content edit saves a new version.

​

Editing project models

• Run AI writeback (run_ai_writeback) - Start a writeback run against the active project’s repository from a natural-language prompt. The repository, project directory, and semantic layer format are resolved server-side from the saved connection — you don’t specify them. Returns immediately with an aiWritebackRunUuid.
• Get AI writeback status (get_ai_writeback_status) - Poll a writeback run by id. Returns the current pipeline stage while the run is in flight, and the pull request URL (or an error message) once it reaches a terminal state.

How the async flow works

run_ai_writeback — start a run

• prompt (string, required) — A clear, self-contained description of the change to make to the dbt project (for example, “Add a total_revenue metric to the orders model as the sum of amount”). When the project has more than one dbt source, name the intended source in the prompt itself (for example, “In the marketing dbt project, …”) — the run reports the available sources back through get_ai_writeback_status if it can’t tell which one you meant.

{
  "aiWritebackRunUuid": "b3f4e0e2-8a2b-4d5f-9a1f-1c2d3e4f5a6b"
}

get_ai_writeback_status — poll for the result

• aiWritebackRunUuid (UUID, required) — The id returned by run_ai_writeback.

{
  "status": "ready",
  "prUrl": "https://github.com/acme-analytics/jaffle-shop/pull/482",
  "errorMessage": null
}

• status is either "pending" (not yet picked up by a worker), an in-progress pipeline stage (for example, "sandbox", "agent", or "pull_request"), or a terminal value: "ready" (finished — check prUrl) or "error" (finished — check errorMessage).
• prUrl is set once status is "ready" and the agent changed at least one file. If the agent decided no change was needed, status is still "ready" but prUrl is null.
• errorMessage is set once status is "error". This also covers the “more than one dbt source” case — the message lists the available sources so the caller can re-run run_ai_writeback naming the intended one in the prompt.

const { aiWritebackRunUuid } = (
  await callMcpTool('run_ai_writeback', {
    prompt: 'Add a total_revenue metric to the orders model as the sum of amount.',
  })
).structuredContent;

while (true) {
  const { status, prUrl, errorMessage } = (
    await callMcpTool('get_ai_writeback_status', { aiWritebackRunUuid })
  ).structuredContent;

  if (status === 'ready') {
    console.log(prUrl ? `PR opened: ${prUrl}` : 'No file changes were needed.');
    break;
  }
  if (status === 'error') {
    throw new Error(errorMessage ?? 'Writeback failed');
  }

  await new Promise((r) => setTimeout(r, 10_000));
}

​

Data app builds

• Generate data app (generate_data_app) - Start building a new app from a name and a brief. Optionally start from an existing dashboard or saved charts, pick a starter template, or apply a theme.
• Iterate data app (iterate_data_app) - Build a new version of an existing app from a follow-up brief. The app keeps its name, slug, and theme unless you ask for a different theme.
• List data app themes (list_data_app_themes) - List the organization’s themes so the assistant can apply one when it builds.
• Get data app build status (get_data_app_build_status) - Check how a build is going, and get the app’s URL once it’s ready. The assistant checks this for you while the build runs.

1. Data apps are enabled for your organization.
2. The caller can create data apps in the active project.

• “Build a data app called Revenue Overview that shows monthly revenue and the top 10 customers, then tell me when it’s ready.”
• “Add a region filter to the Revenue Overview app.”

​

Chart types

• List custom chart types (list_custom_chart_types) - Browse the project’s chart types, including ones installed from the chart library, newest first.
• Find custom chart types (find_custom_chart_types) - Search the project’s chart types by name and description, or fetch one by slug. Each result has the chart type’s inputs, display options, and a link to it in Chart Studio, so the assistant can reuse a chart type that fits before building a new one.
• Create custom chart type (create_custom_chart_type) - Start building a new chart type from a name and a brief. Optionally share the first rows of a completed metric query as sample data, or apply a theme. The sample rows only guide the build; they don’t tie the chart type to that query.
• Iterate custom chart type (iterate_custom_chart_type) - Build a new version of an existing chart type from a follow-up brief. The chart type keeps its inputs, so charts that already use it keep working.

• Render a query with it - render_chart draws a completed metric query with the chart type, binding the query’s fields to the chart type’s inputs. Like other rendered charts, it only displays in MCP App-capable clients.
• Save a chart with it - create_content saves a chart that uses the chart type, with the same field mapping. The saved chart behaves like one built in the Explorer.

• “Show monthly revenue by product category as a calendar heatmap. Build a chart type for it if we don’t have one.”
• “Render the last query with the Calendar Heatmap chart type.”
• “Add a color legend to the Calendar Heatmap chart type.”

​

Scheduled deliveries

• Create scheduled delivery (create_scheduled_delivery) - Schedule an existing chart or dashboard to Slack, email, or another supported destination on a cron schedule. Point the tool at the content by slug and pass the schedule and recipients — the delivery is created against the active project using the caller’s permissions.

1. Allow content changes via MCP is on (Settings → MCP → General).
2. The caller’s role holds the create:ScheduledDeliveries scope.

​

Agent context

• Route agent (route_agent) - Automatically select the best agent for a user prompt within a project. This is the preferred way to pick an agent — it mirrors the AI Router experience in the Lightdash app, so MCP sessions get the same automatic agent selection.
• List agents (list_agents) - Discover available AI agents and their areas of expertise

​

Skills

• List skills (list_skills) - Return the available built-in and custom skills along with their supporting resource files
• Read skill (read_skill) - Read the main SKILL.md instructions for a skill by name (e.g. developing-in-lightdash)
• Read skill resource (read_skill_resource) - Read a supporting resource file for a skill by name and resource path (e.g. resources/dashboard-best-practices.md)

// List available resources
{ "jsonrpc": "2.0", "id": 1, "method": "resources/list", "params": {} }

// Read the discovery index
{ "jsonrpc": "2.0", "id": 2, "method": "resources/read",
  "params": { "uri": "skill://index.json" } }

// Read a specific skill
{ "jsonrpc": "2.0", "id": 3, "method": "resources/read",
  "params": { "uri": "skill://lightdash/developing-in-lightdash/SKILL.md" } }

​

Example conversations

​

Example 1: Verifying your MCP connection

See screenshot

​

Example 2: Setting up a project and finding dashboards

1. Call list_projects to show your available projects
2. Use the “Jaffle Shop” project’s UUID in the next calls
3. Call find_content with your search term to find matching dashboards and charts

See screenshot

​

Example 3: Exploring data and running a metric query

1. Call grep_fields to search for order-related metrics and dimensions (e.g., orders_total_revenue, orders_order_date)
2. Call run_metric_query with the appropriate explore, metrics, dimensions, filters, and sort order to fetch the data and render a visualization

See screenshot

​

Using AI agent context

​

How is this different from Lightdash AI agents?

​

What you get from agent context

• Specialized content: only the data models relevant to that agent’s domain
• Verified answers: curated example queries that demonstrate correct usage of the data model
• Custom instructions: domain-specific rules like “Always filter orders by status = ‘completed‘“

​

Example workflow

1. Choose your project — get_context lists the projects you can access
2. Let the router pick an agent with route_agent — pass the user’s prompt and Lightdash returns the best-fit agent. Use list_agents only when you want to inspect candidates or pick one manually.
3. Ask your questions — the AI assistant passes the agent’s agentUuid to its tool calls, so the agent’s context guides queries

See screenshot: listing agents

See screenshot: setting agent and viewing explores

You are a Sales analyst for Jaffle Shop. Your role is to answer questions
about revenue, orders, customers and subscriptions.

Key guidelines:
- Use the orders explore as the starting point for revenue and order
  volume questions.
- Always include a time dimension when showing trends. Default to monthly
  granularity unless the user specifies otherwise.
- Format currency values in CAD.

See screenshot: querying with agent context

​

Built-in prompt

​

Best practices

• Organizing and naming your data models
• Writing effective documentation and AI hints
• Optimizing for AI assistant performance
• Security and permissions considerations

​

Lightdash Docs MCP

​

Benefits

• Understand Lightdash concepts, configuration, and best practices
• Generate accurate YAML configurations for metrics and dimensions
• Troubleshoot issues using official documentation
• Stay up-to-date with the latest Lightdash features

​

Setup

{
  "mcpServers": {
    "lightdash-docs": {
      "url": "https://docs.lightdash.com/mcp"
    }
  }
}

claude mcp add --transport http lightdash-docs https://docs.lightdash.com/mcp

{
  "mcpServers": {
    "lightdash-docs": {
      "serverUrl": "https://docs.lightdash.com/mcp"
    }
  }
}

​

Availability

• Open source users
• Cloud Pro
• Cloud Enterprise

​

FAQ