Skip to content

CLI and MCP for AI assistants

dbt charts exposes the same capabilities to AI assistants in two ways: dct CLI commands (shell) and an MCP server (dct mcp serve). Both call the same Python APIs — they are thin wrappers over one engine, not two products.

This page explains why both exist, when each is the right choice, and how they relate to agent skills.

Why both?

Surface What it is Best for
CLI Subcommands like dct query, dct validate, dct render — stdout, --json, exit codes Any environment with a shell and dct on PATH
MCP Structured tools (execute_query, validate_board, …) over stdio MCP-native clients, hosted agents, editors without shell

Different agents read different integration layers:

  • Cursor, Codex, Claude Code — shell + optional MCP + file-based skills
  • VS Code / GitHub Copilot agent mode — MCP tools; no project skill directory today
  • The dbt charts Cloud copilot — MCP only; no shell, no local file install

One surface cannot cover all of those. Keeping both avoids forcing every user through MCP setup while still serving clients that only speak MCP.

When to prefer the CLI

Default recommendation: if the agent can run shell commands and dct is installed, use the CLI.

Reasons:

  1. Lower setup friction — pip install dbt-charts is enough. No per-client MCP config, no dct init mcp, no restart-the-IDE step.
  2. Works everywhere — local dev, CI, headless agents, SSH, scripts. Same verbs in every unconstrained environment.
  3. Portable agent knowledge — skills and docs teach dct validate, dct query, dct docs. That vocabulary works even when MCP is not wired up.
  4. Human parity — what the agent runs is what you run in the terminal. Easier to debug and reproduce.
  5. Long-term baseline — the zero-MCP path (dct docs, dct skills, dct validate) stays the floor; MCP is an upgrade, not a prerequisite.

Typical CLI-first setup:

uv tool install dbt-charts   # or: pip install dbt-charts
dct init skills          # install agent skills to file directories
dct init mcp             # optional — only if you also want MCP

Agent skills installed to .agents/skills/ (or agent-specific skill directories) are CLI-oriented — they reference dct verbs, not MCP tool names.

When MCP is required or better

Use MCP when the CLI is unavailable or secondary:

Situation Why MCP
VS Code / Copilot agent mode Agent invokes MCP tools; no shell, no file skill dirs (use MCP get_skill / resources for workflow knowledge)
dbt charts Cloud copilot Controlled environment: no dct subprocess from the agent, no writing to the user's skill dirs — MCP is the only integration
Claude Desktop / some IDE chat UIs Chat is MCP-native; configuring dct mcp serve is the intended path
Structured tool calls MCP returns typed JSON without parsing terminal output — nice when already connected, not worth the setup cost alone

Setup:

dct init mcp             # auto-detect Cursor, VS Code, Claude Code, Codex, …
dct mcp serve            # or let the client spawn this via config

MCP exposes the same operations under tool names (e.g. validate_board, execute_query, docs). Skills served over MCP use that vocabulary; the registry hides CLI-only skills like dataface-mcp-setup from MCP clients.

Skills: file install vs CLI lookup vs MCP

Workflow knowledge (build, review, design patterns) ships as agent skills — SKILL.md files in the wheel.

Delivery Surface When
dct init skills (file copy to agent dirs) CLI-rendered files in .agents/skills/ Local agents — Cursor, Codex, Claude Code, GitHub Copilot Coding Agent
dct skills <name> CLI Fallback, humans, CI, zero-MCP
MCP get_skill / resources MCP Copilot, the dbt charts Cloud copilot, any connected MCP client

File-installed skills assume the agent can run dct commands. MCP-delivered skills assume connected tools. Same content, different vocabulary — picked at serve/install time.

Quick decision guide

Can the agent run shell commands and is dct installed?
├─ YES → Prefer CLI (dct query, dct validate, dct docs, dct skills)
│         Install skills:  dct init skills
│         Optional MCP:    dct init mcp
└─ NO  → Use MCP (dct init mcp or hosted integration)
          Skills via get_skill / dataface://guide/* resources

Same engine, different wire format

Both surfaces delegate to dbt_charts.agent_api:

  • dct validate ↔ MCP validate_board
  • dct query ↔ MCP execute_query / query_board
  • dct docs ↔ MCP docs
  • dct skills ↔ MCP list_skills / get_skill

Pick one primary surface per environment. Do not configure MCP and teach the agent to shell out for the same operation unless you have a reason (e.g. debugging). In mixed setups, CLI for execution, MCP when CLI is impossible is the usual split.

  • dct init — project bootstrap, skills install, MCP wiring
  • dct skills — skill catalog and search
  • dct mcp — MCP server commands and tool list