Skip to content

dft 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 dft is installed; use MCP when the environment is MCP-only (VS Code/Copilot agent mode, the Dataface Cloud copilot) or when structured tool calls are already wired up.

dft mcp [OPTIONS] COMMAND [ARGS]

Subcommands

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

dft mcp serve

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

dft mcp serve [OPTIONS]

Options

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

Examples

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

Manual client configuration

In most cases, dft 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": "dft",
      "args": ["mcp", "serve"]
    }
  }
}

For a nested project directory:

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

What the MCP server exposes

CLI verbs wrapped as MCP tools that agents call directly:

Face authoring & validation

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

Data discovery

  • search_dashboards — keyword search across face 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_face — inspect a query defined inside a face 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 dft 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://dashboards List of all dashboards in the project with metadata
dataface://dashboard/{path} YAML content and compiled structure of one dashboard
dataface://docs/all The complete YAML reference — same content as dft 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 dft docs <topic>)
dataface://guide/dashboard-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/dashboard-build Recommended build-test-iterate workflow, caching, and tool usage patterns
dataface://guide/dashboard-review Structural (YAML + validate) and visual (rendered image) review workflow

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