` call is independent. Output returns to context and Claude decides the next step. A four-step pipeline costs four schema triggers and four full responses.
### 2.3 Auditability
**CLI commands are plaintext and recorded in shell history.** `auditd`, syscall tracing, and bash history all provide audit trails. In CI, the `run:` blocks in git log are deterministic records.
**MCP calls happen at the agent execution layer** and require extra logging infrastructure (hooks, subagent logs) to be traceable (see [04-6 Hooks](/en/code-agent/customization/hooks) for partial support -- it is not the default). For high-compliance scenarios (finance, healthcare, academic review), CLI's auditability is a structural advantage.
### 2.4 Authentication and state management
**CLI piggybacks on OS-level authentication:** `gh auth login`, `aws configure`, and `gcloud auth login` store tokens in the OS keychain or the appropriate `~/.config` directory. Subsequent commands carry credentials automatically. Claude Code's Bash tool allows fine-grained read control over credential files via `permissions.deny` \[2].
**MCP authentication is each server's own responsibility:** HTTP servers use OAuth (detailed in [04-9 MCP Integration](/en/code-agent/customization/mcp-integration)); stdio servers receive keys via `env`. Most servers have no session state, though some (Notion editing, Atlassian changes) do. State management is correspondingly more complex and requires understanding each server individually.
## 3. Why CLI-first
Distilling the differences above into four concrete reasons:
1. **CLI is the ecosystem's official, first-party path.** `gh` is GitHub's official CLI, `kubectl` is the official K8s CLI, `aws` is the official AWS CLI. Documentation is complete, versions are stable, community coverage is broad, and upstream changes land here first. Bypassing it means bypassing a maintained, well-lit road.
2. **Output format is under your control.** `gh pr list --json number,title,state` selects exactly the fields you need. An MCP call returns the full structured object -- the fields you want and the fields you do not all enter context together.
3. **No extra context consumed.** The Bash tool schema is fixed. MCP tool descriptions grow linearly with the number of connected servers.
4. **Debugging path is clear.** CLI failures produce a specific exit code and stderr. MCP failure diagnosis varies by server (protocol error, expired credentials, and nonexistent tool all look different).
**There is no official "CLI first" directive**
As of 2026-06, Anthropic's official documentation does not use the phrase "CLI first" in either the \[permissions] or \[MCP] sections \[1, 2]. "CLI-first" is a practical strategy this Playbook derives from the official architecture: Bash is a core tool type, read-only commands need no prompt, and permissions are configurable down to the command prefix. Those design choices put Bash in the highest-leverage position -- CLI-first is simply following the path that was already laid down.
## 4. When to use MCP (fallback trigger conditions)
CLI-first is the default. Switch to MCP only when at least one of the following is clearly true:
| Trigger | Example |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| The service has no CLI at all | Many SaaS tools (early Notion, Linear, some Sentry features) expose only a REST API |
| CLI requires authentication that the agent environment cannot complete | OAuth flow requires interaction; device code flow is not available |
| CLI has hit its rate limit | Multiple clients share the same token pool; an MCP server can have its own independent pool |
| A single server needs to be shared across multiple MCP clients | Same server used by both Claude Code and Cursor, avoiding two separate configurations |
| The operation requires a structured, typed response | Schema validation is one of MCP's design goals |
**Not "MCP works too, let's try both"**
The fallback rule: switch only when a condition is clearly met. Do not install a server because "MCP might also work" -- every additional server carries a permanent context cost, a permissions surface, and a supply-chain risk. Pick one path per workflow and do not go back to mixing them (next section).
## 5. Worked example: the same operation over CLI and MCP
### 5.1 Scenario
Query the latest 10 open PRs from a GitHub repo, listing number, title, author, and draft status.
### 5.2 CLI path
```bash theme={null}
gh pr list --repo owner/repo --state open --limit 10 \
--json number,title,author,isDraft \
| jq -r '.[] | "\(.number)\t\(.title)\t\(.author.login)\tdraft=\(.isDraft)"'
```
Characteristics:
* Single stdout output; pipe directly to `| head`, `| wc -l`, or `| column -t` for post-processing.
* Failure exits non-zero with a clear stderr message ("API rate limit exceeded", "auth required").
* Token cost: 0 schema loading + roughly 800 tokens of structured output (10 PRs as JSON).
* From Claude's perspective, the Bash tool schema is already resident -- this call adds nothing.
### 5.3 MCP path
Assuming the official GitHub MCP server is installed (`mcp__github__list_pull_requests`):
```text theme={null}
Call mcp__github__list_pull_requests(owner='owner', repo='repo', state='open', per_page=10), then summarize the result
```
Characteristics:
* Tool schema enters context (tool search means it loads on trigger, but once loaded it occupies context).
* Returns a complete structured object, potentially including `head`, `base`, `user`, and other fields you will not use -- typically 1,500-3,000 tokens.
* A derived field like draft status requires Claude to compute it inside context.
* Error messages when it fails vary by server design; some are not human-friendly.
### 5.4 Side-by-side comparison
| Dimension | CLI (`gh`) | MCP (`mcp__github__*`) |
| ------------------------ | ---------------------------------------- | --------------------------------------------------- |
| Schema loading cost | 0 (shared Bash tool schema) | Loaded each time the server connection is triggered |
| Response tokens per call | \~800 (lower after trimming) | \~1,500-3,000 (full object) |
| Composability | pipe / `jq` / `xargs` / redirect to file | Claude must compute inside context |
| Auditability | shell history / git log / `auditd` | Requires hook or server log |
| Debugging | Explicit exit code + stderr | Depends on server implementation |
| Authentication | `gh auth login` once, permanent | OAuth token expires and must be renewed |
**Quantifying the difference**
Assume this query runs 50 times a day. The CLI path burns roughly 0.6M tokens per month (response side); the MCP path burns roughly 2.3M tokens per month (schema + response). At Claude Sonnet 4.6 pricing, the monthly gap is a few dollars. Stack several servers and it becomes tens of dollars. CLI-first is not just about saving tokens -- it is about preserving context budget for work that actually requires it.
## 6. Anti-pattern: mixing CLI and MCP
This is the most common source of silent bugs. A concrete scenario:
```bash theme={null}
# You manually run this in your shell: create a PR
gh pr create --base main --head feature-x --title "WIP" --body "..."
```
At the same time, the agent receives "create a PR for me," has no knowledge of your manual action, and proceeds via MCP:
```text theme={null}
mcp__github__create_pull_request(...)
```
Result: two PRs coexist with inconsistent messages; CI triggers once for the `gh` side and once for the MCP side. State has split.
Rules:
1. **Pick one path per operation:** if you use CLI today, stay on CLI; if MCP, stay on MCP -- consistent across the session.
2. **Do not go back after a fallback switch:** only switch to MCP when CLI is unavailable; do not "try both to see which works."
3. **Document across sessions:** add a line to `CLAUDE.md` -- "This project uses `gh` CLI exclusively; no GitHub MCP server is installed" -- to give every session a consistent starting default.
## 7. Tool comparison
**Naming clarification**
Claude Code's Bash tool is the interface through which the agent calls the shell; the `claude` CLI is the command used to invoke Claude Code itself. They operate at different levels. For OpenAI Codex, Antigravity, and GitHub Copilot CLI, refer to each vendor's current documentation for Bash tool and MCP details. Cursor is a third-party IDE (Anysphere) and appears here only for a brief reference column.
## Hands-on exercises
**30-minute practice**
1. **Build a CLI-first checklist** (10 minutes): list 10 operations common in your workflow (query issues, query PRs, run tests, view logs, query DB, deploy, etc.) and mark each "CLI available," "needs MCP fallback," or "built-in tool is enough." This list becomes your default starting point next session.
2. **Compare both paths on the same operation** (15 minutes): pick one operation you use often (such as fetching GitHub issues), complete it via CLI first (estimate token cost: use `wc -w` or `wc -c` to approximate stdout size), then complete it via MCP (observe how much context it actually consumes). Quantify the gap and decide which path becomes your default.
3. **Detect mixed usage** (5 minutes): scan `~/.bash_history` and recent session transcripts for signs of CLI and MCP being called in parallel for the same service. Flag any you find and decide whether to consolidate.
## Common pitfalls
**Anti-pattern list**
* **Defaulting to MCP because "it's AI-native and therefore more modern":** this ignores the structural advantages CLI has in composability and token cost. Newer does not mean better suited to your scenario.
* **Keeping MCP active out of inertia when a CLI exists:** existing configuration is not a default. Evaluate the fallback trigger conditions for every new operation.
* **Running CLI and MCP in parallel for the same service within a session:** silent source of state inconsistency bugs. Commit to one path.
* **Treating the Bash tool as a universal fallback and wrapping even simple grep calls as MCP servers:** if the shell already does it, packaging it as MCP adds complexity for no gain. The opposite extreme of CLI-first is just as wasteful.
* **Not documenting a fallback switch in `CLAUDE.md`:** the next session starts over with no memory of the decision. Write it into the rules file.
* **Treating `gh pr list` and `mcp__github__list_pull_requests` as fully equivalent:** their token costs, auditability, and debugging paths differ. Equivalence is an illusion.
## Self-check
**The bar for passing this unit**
1. Facing a new integration requirement, can you decide "CLI available or need MCP" within 30 seconds? State your decision criteria.
2. Can you list at least three concrete advantages CLI has over MCP? Give a real example for each.
3. In your current session (or your most recent one), is there any instance of CLI and MCP being used in parallel for the same service? List them and decide whether to consolidate.
4. Does your `CLAUDE.md` document a CLI-first preference? If not, add a line now.
## Sources and further reading
Factual claims are grounded in official documentation; fast-changing items are annotated as of 2026-05.
* \[1] Anthropic, "Connect Claude Code to tools via MCP," code.claude.com, 2026. \[Online]. Available: [https://code.claude.com/docs/en/mcp](https://code.claude.com/docs/en/mcp) (as of 2026-06; MCP transport, scope, tool search)
* \[2] Anthropic, "Configure permissions," code.claude.com, 2026. \[Online]. Available: [https://code.claude.com/docs/en/permissions](https://code.claude.com/docs/en/permissions) (as of 2026-06; Bash tool as core tool type, read-only command list, allow / deny / ask rules with `Bash(specifier)` form, shell specifier syntax)
* \[3] OpenAI, "Codex CLI," developers.openai.com, 2026. \[Online]. Available: [https://developers.openai.com/codex](https://developers.openai.com/codex) (as of 2026-06; codex CLI commands, --approval-mode, sandbox execution, MCP config.toml location)
* \[4] Google, "Gemini CLI," google-gemini.github.io, 2026. \[Online]. Available: [https://google-gemini.github.io/gemini-cli/](https://google-gemini.github.io/gemini-cli/) (as of 2026-06; gemini CLI commands, shell tool, --sandbox, MCP settings.json config, GEMINI\_API\_KEY authentication)
* \[5] GitHub Docs, "GitHub Copilot CLI," docs.github.com, 2026. \[Online]. Available: [https://docs.github.com/en/copilot/how-tos/copilot-cli](https://docs.github.com/en/copilot/how-tos/copilot-cli) (as of 2026-06; gh copilot suggest / explain, gh auth login, \~/.copilot/mcp-config.json)
* \[6] Cursor, "MCP," cursor.com, 2026. \[Online]. Available: [https://cursor.com/docs/cli/mcp](https://cursor.com/docs/cli/mcp) (as of 2026-06; .cursor/mcp.json and \~/.cursor/mcp.json locations, stdio and Streamable HTTP transport)
* MCP integration configuration: [04-9 MCP Integration](/en/code-agent/customization/mcp-integration).
* Built-in tool inventory: [04-8 Vendor Built-in Tools](/en/code-agent/customization/vendor-builtin-tools).
* Writing `CLAUDE.md`: [04-1 CLAUDE.md and Memory Files](/en/code-agent/customization/claude-md-memory).
* Supply-chain risk for shell tools: [03-3 Security, Privacy, and Supply-Chain Risk](/en/code-agent/judgment/security-privacy-supply-chain).
* Bash auditability and permission tightening: [04-6 Hooks](/en/code-agent/customization/hooks).