CLI vs MCP: What To Use, When

June 26, 2026 · View on GitHub

Both interfaces are valid and both execute the same core command catalog.

flutter-mcp-toolkit: canonical direct command-line interface for scripts, CI, snapshots, and deterministic automation. fmtk is the short alias for the same executable.
flutter-mcp-toolkit-server (MCP server): assistant-facing interface over MCP for Codex/Claude/Cursor workflows.

Recommended default: start with CLI, then layer MCP client workflows on top.

If you're not sure whether to use CLI or MCP mode, run flutter-mcp-toolkit init <your-agent> and let it auto-detect. Override with --mode mcp or --mode cli if needed. Skill install is separate from mode: use init (skills + MCP config) or npx skills add Arenukvern/mcp_flutter (skills only) — AI agent overview.

Why We Have Both

They solve different UX problems:

CLI is optimized for reproducible terminal automation.
MCP is optimized for conversational tool use inside AI clients.

Internally they share the same execution core, so behavior and command semantics stay aligned.

Quick Difference Table

Topic	CLI (`flutter-mcp-toolkit`, alias `fmtk`)	MCP Server (`flutter-mcp-toolkit-server`)
Primary user	developers, CI, automation scripts	AI assistants and agent chat clients
Interface	terminal commands / JSON args	MCP tools/resources via client
Transport	local process execution	stdio MCP protocol between client and server
Best for	snapshots, diff/bundle artifacts, repeatable runs	interactive debugging and assistant-led workflows
State handling	explicit state/snapshot/bundle commands	conversation/tool-call driven operations
Typical trigger	shell script, make target, CI pipeline	prompt in Codex/Claude/Cursor

When To Use CLI

Use CLI when you need:

deterministic, scriptable runs
artifacts (snapshot create, snapshot diff, bundle create)
non-interactive CI jobs
explicit one-shot command execution in terminal
reliable preflight gating before app-level inspection (doctor, get_extension_rpcs)

Example:

fmtk exec --name get_vm --args '{}'

Need command patterns you can copy quickly? CLI quick recipes

When To Use MCP

Use MCP server when you need:

AI assistant-driven debugging loops
tool invocation from chat/editor agents
mixed workflows with screenshots, app errors, and dynamic tools during conversation

Example (conceptual). MCP tool names carry the fmt_ capability prefix (v3.0.0+); the CLI catalog uses unprefixed names.

{
  "name": "fmt_get_app_errors",
  "arguments": {}
}

Use Both Together

A common pattern:

Start with CLI preflight: fmtk doctor --json and fmtk exec --name get_extension_rpcs --args '{}'.
Use CLI for reproducible screenshot/layout/error baselines.
Use MCP in editor/chat for interactive follow-up loops.
Share CLI outputs/artifacts back into assistant workflows.

Decision Guide

Need deterministic automation, CI, or trustworthy runtime gating: use CLI first.
Need interactive assistant workflow right now: use MCP after CLI preflight.
Need both interactive and reproducible workflows: use both (CLI baseline + MCP iteration).

Important Parity Notes

VM target selection uses the same nested connection model in both interfaces.
Multi-target ambiguity returns guidance (connection_selection_required), then retry with connection.targetId.
Core capability definitions come from the same command catalog.
High-signal debugging commands are shared: discover_debug_apps, capture_ui_snapshot, inspect_widget_at_point.
Low-signal diagnostics (get_active_ports, dynamicRegistryStats) remain CLI-available but are not MCP-exposed by default.
Debug/eval batteries should group existing primitives (--log-level debug, --output-dir, --save-images, doctor --json, validate-runtime, batch, exec --name diagnose) before adding public verbs. Repeatable scenario documents belong in flutter_harness.