# CLI vs MCP: What To Use, When

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](/ai_agents/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:

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

Need command patterns you can copy quickly?
[CLI quick recipes](/start_here/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.

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

## Use Both Together

A common pattern:

1. Start with CLI preflight: `fmtk doctor --json` and `fmtk exec --name get_extension_rpcs --args '{}'`.
2. Use CLI for reproducible screenshot/layout/error baselines.
3. Use MCP in editor/chat for interactive follow-up loops.
4. 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 E2E scenarios as checked-in Dart belong in `flutter_mcp_harness` ([`packages/harness`](https://github.com/Arenukvern/mcp_flutter/tree/main/packages/harness), ADR-0015); the declarative scenario-document experiment (external `flutter_harness`, ADR-0012) is retired (ADR-0017).

## Related Docs

- [MCP configuration](/core/mcp_configuration)
- [CLI quick recipes](/start_here/cli_quick_recipes)
- [Interaction cookbook](/guides/interaction_cookbook)
- [AI agent execution playbook](/ai_agents/execution_playbook)
- [Server architecture details](/core/project_architecture)