Skip to content

dct mcp

MCP (Model Context Protocol) server commands for AI assistant integration.

For when to use MCP vs the CLI, see CLI and MCP for AI assistants. Prefer the CLI when the agent has shell access and dct is installed; use MCP when the environment is MCP-only (VS Code/Copilot agent mode, the dbt charts Cloud copilot) or when structured tool calls are already wired up.

dct mcp [OPTIONS] COMMAND [ARGS]

Subcommands

Command Purpose
dct mcp serve Start the MCP server for AI assistant integration.

dct mcp serve

Starts an MCP server that lets AI assistants like Cursor, Claude Code, Claude Desktop, and ChatGPT interact with your dbt charts project. The server runs in stdio mode — the standard transport for MCP-compatible tools.

dct mcp serve [OPTIONS]

Options

Flag Description
--project-dir PATH dbt charts or dbt project directory. Default: current directory.

Examples

dct mcp serve
dct mcp serve --project-dir ./my-project

Manual client configuration

In most cases, dct init mcp writes the right config for you. For manual setup of Claude Code (~/.config/claude/config.json) or Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "dataface": {
      "command": "dct",
      "args": ["mcp", "serve"]
    }
  }
}

For a nested project directory:

{
  "mcpServers": {
    "dataface": {
      "command": "dct",
      "args": ["mcp", "serve", "--project-dir", "/absolute/path/to/project"]
    }
  }
}

What the MCP server exposes

CLI verbs wrapped as MCP tools that agents call directly:

Board authoring & validation

  • validate_board — fast YAML schema + cross-reference validation
  • render_board — produce SVG / HTML / PNG / PDF
  • describe_board — describe a dashboard's queries, charts, variables, and layout

Data discovery

  • search_boards — keyword search across board files
  • docs — read packaged YAML docs

Query inspection

  • execute_query — run a query and return the result rows
  • describe_query — return resolved SQL, dialect, and column schema
  • query_board — inspect a query defined inside a board file

Agent skills

  • list_skills — enumerate packaged agent skill recipes
  • get_skill — read a specific skill
  • search_skills — filter packaged skills by keyword

Diagnostic code lookup

  • list_diagnostic_codes — list every registered error/warning code with a one-line summary, optionally filtered by level
  • get_diagnostic_code — full documentation for one error or warning code

See dct skills for the agent-facing skill catalog that ships alongside.

Resources

Beyond tools, the MCP server exposes read-only dataface:// resources — content an assistant can fetch by URI without a tool call:

Resource Content
dataface://boards List of all dashboards in the project with metadata
dataface://board/{path} YAML content and compiled structure of one dashboard
dataface://docs/all The complete YAML reference — same content as dct docs all
dataface://docs/reference Generated field-level YAML reference (just gen-yaml-reference output)
dataface://docs/error-reference Generated reference of every ERR-* error code
dataface://docs/warning-reference Generated reference of every WARN-* warning code
dataface://docs/{topic} One H2 section of the reference (same slugs as dct docs <topic>)
dataface://guide/board-design Design principles for dashboards — chart choice, layout for at-a-glance monitoring
dataface://guide/report-design Design principles for narrative, data-driven reports
dataface://guide/board-build Recommended build-test-iterate workflow, caching, and tool usage patterns
dataface://guide/board-review Structural (YAML + validate) and visual (rendered image) review workflow

The server also honors DCT_CACHE_PATH: if set, the query-result cache persists to that DuckDB file instead of staying in-memory for the process lifetime.