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 skills intro         # what the tool is, and which skill to read next
dct init skills          # optional: copy the skills into this repo's agent directories
dct init mcp             # optional; only if you also want MCP

An agent that has never seen dbt Charts needs only the first two lines, so the sentence to hand one is short:

I want to make charts of this data with dbt Charts. Run `uv tool install dbt-charts`, then `dct skills intro`, and follow what it prints.

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 (for example, validate_board, execute_query, docs). Skills served over MCP use that vocabulary; the registry hides CLI-only skills like 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.

Reading the docs without the CLI

An agent with only an HTTP fetch tool can read these docs as Markdown instead of HTML:

  • https://docs.dbtcharts.com/llms.txt indexes the pages that matter most.
  • https://docs.dbtcharts.com/llms-full.txt is every page in one file.
  • Every page is also published as Markdown at its source path, for example https://docs.dbtcharts.com/quick-guide.md or https://docs.dbtcharts.com/charts/index.md.
  • Any page URL returns its Markdown when the request sends Accept: text/markdown:
curl -H "Accept: text/markdown" https://docs.dbtcharts.com/quick-guide/

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 / dct://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 (for example, 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