Skip to content

CLI and MCP for AI assistants

There are three ways to put an AI assistant to work on dbt Charts. Pick by where the assistant runs, not by which protocol it speaks:

You're using Use Setup
Claude or ChatGPT (chat apps, web, desktop, mobile) The Claude & ChatGPT connector, a hosted MCP server for dbt Charts Cloud Paste https://dbtcharts.com/mcp into the app's connector settings. No CLI, no git, no coding agent
A coding agent with a shell (Claude Code, Codex, Cursor) working in your project The dct CLI plus agent skills uv tool install dbt-charts, then dct skills chart
An agent that can't run shell commands but works on a local checkout (VS Code / GitHub Copilot agent mode) The local MCP server, dct mcp serve dct init mcp

If you just want to ask questions about your boards and data, or have the AI draw a chart, the connector is the one you want. The rest of this page is about the two local surfaces, which matter when you author a project's YAML on your own machine.

Local surfaces: CLI and MCP

The dct CLI and dct mcp serve expose the same capabilities: both call the same Python APIs, so they are thin wrappers over one engine, not two products.

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
Local MCP Structured tools (execute_sql, render_board, ...) over stdio MCP-only clients that edit a local project and have no shell

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 teach dct validate, dct query, dct skills. 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 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 chart         # board and chart grammar, and the build-render-fix loop
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 chart`, 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 the local MCP server is the right choice

The local MCP server covers a short list of cases, all of them an MCP-only client working on your own machine's files or data:

Situation Why local MCP
VS Code / GitHub Copilot agent mode The agent calls MCP tools and has no project skill directory; the editor extension's Setup AI Integration (MCP) command wires it up
An MCP-only client against data that never leaves your machine A local DuckDB file or a warehouse the hosted connector can't reach; the server runs next to the data
No dbt Charts Cloud account The open-source engine only; nothing hosted to connect to

Everywhere else, prefer the CLI if the agent has a shell, or the hosted connector if it's a chat app. Admin work (members, access grants, audit exports) belongs to the CLI's dct cloud verbs, not to either MCP server.

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, render_board, execute_sql, describe_board). 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 Claude & ChatGPT connector, 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

Is the assistant the Claude or ChatGPT app?
├─ YES → Claude & ChatGPT connector: https://dbtcharts.com/mcp
└─ NO  → Can the agent run shell commands, and is dct installed?
         ├─ YES → Prefer CLI (dct query, dct validate, dct skills)
         │         Install skills:  dct init skills
         └─ NO  → Local MCP (dct init mcp)
                   Skills via get_skill / dct://guide/* resources

Same engine, different wire format

Both surfaces delegate to dbt_charts.agent_api:

  • dct render ↔ MCP render_board
  • dct query ↔ MCP execute_sql
  • 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.