MCP

sqldash mcp runs a Model Context Protocol server that gives AI agents your governed metrics, dashboards, and data agents. Agents ask for metrics by name and sqldash writes the SQL, so an agent never needs raw warehouse access and never invents its own definition of revenue.

The server speaks MCP over stdio. Your MCP client starts it as a local command, and it queries the warehouse with the credentials on your machine.

Set it up

Pick your client, choose how you run sqldash, add your warehouse extra if you use one, and enter the project path. Copy what appears into the place it says.

Both ways of running sqldash work. uvx sqldash mcp downloads and runs the latest release on demand, so there is nothing to install or upgrade. If you installed sqldash with uv tool install sqldash or pip, the command is just sqldash mcp, which starts faster and uses exactly the version you installed.

The project can be a directory, a single dashboard file, or a git URL, and --all serves every repo you have registered.

uvx sqldash mcp /path/to/project
uvx sqldash mcp git@github.com:acme/analytics.git
uvx sqldash mcp --all

codex mcp add sqldash -- uvx --from 'sqldash[snowflake]' sqldash mcp /path/to/project
codex mcp add sqldash -- sqldash mcp /path/to/project

Some desktop apps do not inherit your shell’s PATH. If a client says it cannot find uvx or sqldash, run which uvx or which sqldash and use that absolute path as the command.

The sections below show each client’s setup in full.

Codex

codex mcp add sqldash -- uvx sqldash mcp /path/to/project

This writes an entry to ~/.codex/config.toml, which the Codex CLI and the Codex IDE extension both read, so one setup covers both. Run codex mcp list to check it, or type /mcp inside a Codex session. You can also add it by hand.

[mcp_servers.sqldash]
command = "uvx"
args = ["sqldash", "mcp", "/path/to/project"]

To check agent answers with Codex, see graded runs in Agents and evaluations.

Claude Code

Add the server from inside the project.

claude mcp add sqldash -- uvx sqldash mcp .

--scope project writes it to a .mcp.json file you can commit, so everyone who opens the repo in Claude Code gets the same server. --scope user makes it available in all your projects. Check it with claude mcp list.

Cursor

Create .cursor/mcp.json in the project to share it with the repo, or ~/.cursor/mcp.json to use it everywhere.

{
  "mcpServers": {
    "sqldash": {
      "command": "uvx",
      "args": ["sqldash", "mcp", "/path/to/project"]
    }
  }
}

Claude Desktop

Open Settings, then Developer, then Edit Config. That opens claude_desktop_config.json, which lives in ~/Library/Application Support/Claude/ on macOS and %APPDATA%\Claude\ on Windows. Add the server and restart the app.

{
  "mcpServers": {
    "sqldash": {
      "command": "/Users/you/.local/bin/uvx",
      "args": ["sqldash", "mcp", "/Users/you/work/analytics"]
    }
  }
}

Claude Desktop does not start in your project folder, so use absolute paths for both the command and the project.

GitHub Copilot in VS Code

GitHub Copilot’s agent mode reads .vscode/mcp.json in the workspace.

{
  "servers": {
    "sqldash": {
      "type": "stdio",
      "command": "uvx",
      "args": ["sqldash", "mcp", "${workspaceFolder}"]
    }
  }
}

Windsurf

Add the server to ~/.codeium/windsurf/mcp_config.json.

{
  "mcpServers": {
    "sqldash": {
      "command": "uvx",
      "args": ["sqldash", "mcp", "/path/to/project"]
    }
  }
}

Gemini CLI

Add the server to ~/.gemini/settings.json, or to .gemini/settings.json inside the project.

{
  "mcpServers": {
    "sqldash": {
      "command": "uvx",
      "args": ["sqldash", "mcp", "."]
    }
  }
}

Any other client

Any client that can launch a local stdio server works. Give it uvx as the command and ["sqldash", "mcp", "<project>"] as the arguments. Pass warehouse credentials the same way you would in a terminal, either through a local profile or through environment variables set in the client’s server config. See Setup.

What agents can do

Once connected, ask in plain language. The agent picks the tools.

• “Which metrics do we have for orders?”
• “How did revenue by region do over the last 30 days compared to the month before?”
• “Add a tile to the revenue dashboard showing average order value by category.”

Here is what a query_metric call looks like when an agent asks about revenue by region. These are the arguments it sends.

{
  "name": "revenue",
  "dimensions": ["region"],
  "start": "-30d",
  "end": "today",
  "compare": "previous_period"
}

This is the response from the demo project, trimmed. It carries the SQL sqldash compiled, the rows, and the comparison window.

{
  "sql": "SELECT region AS \"region\", SUM(amount) AS \"revenue\"\nFROM orders\nWHERE order_date >= ? AND order_date < ?\nGROUP BY 1\nORDER BY 1",
  "columns": [{"name": "region", "type": "string"}, {"name": "revenue", "type": "float"}],
  "rows": [["apac", 51669.37], ["eu", 82629.99], ["us", 106091.64]],
  "row_count": 3,
  "truncated": false,
  "row_limit": 1000,
  "compare": {
    "mode": "previous_period",
    "label": "previous period",
    "window": {"start": "2026-07-27", "end": "2026-08-26"},
    "rows": [["apac", 46771.12], ["eu", 77790.07], ["us", 106871.71]]
  }
}

The values are bound as query parameters, the ? marks in the SQL. The agent passed names and values, never SQL.

Tools

filters takes dimension values, such as {"region": "eu"}, lists for several values, or an operator such as {"op": ">=", "value": 100}. start and end take ISO dates or tokens like -30d, mtd, and ytd. compare needs both start and end, or a dashboard whose date filter has a default. dashboard also applies that dashboard’s filter defaults, and anything they narrowed that you did not ask for comes back in a scope_note field.

The server caps every call at 1000 rows, and --row-limit changes that cap. limit is the caller’s own, smaller cap. Every result carries row_limit, the cap that applied, and truncated, which says whether it clipped the answer, so a short series is never mistaken for a complete one.

run_sql is a keyword check and a row cap, not a sandbox. The grants of the credential sqldash connects with are the real guardrail, so give it a read-only role before you turn --allow-sql on.

Data agents and their tools

Each agent in agents.yaml is served as an MCP prompt, and each of its data tools as an extra tool. In the demo project, the server lists a finance_analyst prompt next to the built-in tools, plus revenue_health and top_categories. How a client presents prompts depends on the client. Some offer them as slash commands or skills, and others only use the tools. See Agents and evaluations.

Many repos in one server

Register the repos whose metrics matter, then serve them all at once.

sqldash repo add git@github.com:acme/payments.git
sqldash repo add git@github.com:acme/growth.git

codex mcp add sqldash -- uvx sqldash mcp --all

claude mcp add sqldash -- uvx sqldash mcp --all

With --all, metric names carry their repo, as in payments/revenue and growth/signups. Agents are named repo/agent, and agent tools repo__tool, because MCP tool names cannot contain a slash. See Many repos.

How agents change dashboards

There is no tool that saves a file. When an agent builds or edits a dashboard, it writes the YAML itself in your repo, calls validate_dashboard to check it, and you review the change in a pull request like any other code. validate_dashboard applies the same rules as sqldash lint, so a file that passes for the agent also passes in CI.

Give agents the context up front

sqldash export context writes a markdown summary of the project’s metrics, dashboards, and agents. Codex reads AGENTS.md and Claude Code reads CLAUDE.md, so put the summary where your agent looks.

sqldash export context --out sqldash-context.md

If the repo already has an AGENTS.md or CLAUDE.md, paste the summary into it rather than replacing it, so existing instructions survive. Start a new agent session afterwards so the agent picks it up, and export again when the metrics change.