Skip to content

CLI and MCP for AI assistants

Dataface exposes the same capabilities to AI assistants in two ways: dft CLI commands (shell) and an MCP server (dft 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 dft query, dft validate, dft render — stdout, --json, exit codes Any environment with a shell and dft on PATH
MCP Structured tools (execute_query, validate_dashboard, …) over stdio MCP-native clients, hosted/cloud 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
  • Hosted Dataface (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 dft is installed, use the CLI.

Reasons:

  1. Lower setup friction — pip install dataface is enough. No per-client MCP config, no dft 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 dft validate, dft query, dft 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 (dft docs, dft skills, dft validate) stays the floor; MCP is an upgrade, not a prerequisite.

Typical CLI-first setup:

pip install dataface
dft init skills          # install agent skills to file directories
dft 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 dft 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)
Hosted / cloud copilot Controlled environment: no dft 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 dft 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:

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

MCP exposes the same operations under tool names (e.g. validate_dashboard, 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
dft init skills (file copy to agent dirs) CLI-rendered files in .agents/skills/ Local agents — Cursor, Codex, Claude Code, GitHub Copilot Coding Agent
dft skills <name> CLI Fallback, humans, CI, zero-MCP
MCP get_skill / resources MCP Copilot, cloud, any connected MCP client

File-installed skills assume the agent can run dft 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 dft installed?
├─ YES → Prefer CLI (dft query, dft validate, dft docs, dft skills)
│         Install skills:  dft init skills
│         Optional MCP:    dft init mcp
└─ NO  → Use MCP (dft init mcp or hosted integration)
          Skills via get_skill / dataface://guide/* resources

Same engine, different wire format

Both surfaces delegate to dataface.agent_api:

  • dft validate ↔ MCP validate_dashboard
  • dft query ↔ MCP execute_query / query_face
  • dft docs ↔ MCP docs
  • dft 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.

  • dft init — project bootstrap, skills install, MCP wiring
  • dft skills — skill catalog and search
  • dft mcp — MCP server commands and tool list
  • dft chat — terminal agent (CLI-native)