mirror of
https://github.com/magnus919/agent-skills.git
synced 2026-09-11 19:47:12 +03:00
Magnus Hedemark
a1c83765a3
10 universal patterns for building CLI tools that AI agents can use reliably: non-interactive, --json, --dry-run, idempotent, lazy auth, progressive help, and more. Includes a bash scaffold template, Python API client reference, advanced edge-case patterns, MCP-vs-CLI decision framework, and an improvement cycle for iterating on shipped tools. Principles grounded in real failures from building 15+ agent-facing CLIs across multiple API services. Signed-off-by: Jasper <magnus@groktop.us>
3.5 KiB
3.5 KiB
MCP vs CLI — Discourse Summary & Decision Framework
The Core Argument
CLI-first design for agent tools vs MCP servers — what the debate is actually about, not the noise.
Key Sources
| Source | Key Claim |
|---|---|
| Eric Zakariasson — "Building CLIs for Agents" (X thread) | CLIs designed for agents need --json, --dry-run, examples in help, and non-interactive mode. Most CLIs assume a human. |
| ScaleKit Benchmarks (scalekit.com/blog/mcp-vs-cli-use) | 9-32× token savings for CLI over MCP on GitHub automation. 100% reliability (CLI) vs 72% (MCP). The gap is schema injection — 43 tool definitions per turn, agent uses 1-2. |
| Ronnie Rocha — "Don't Build MCPs, Build CLI Tools" (ronnierocha.dev) | MCP was designed for sandboxed agents (IDE plugins, web assistants). Terminal-native agents already have access — they don't need a bridge. MCP tax: context bloat, no composability, no pipes, serialized overhead. |
| Garry Tan (X) | "MCP sucks honestly. It eats too much context window… I vibe coded a CLI wrapper for Playwright tonight in 30 minutes… worked 100x better." |
| Peter Steinberger (steipete) — MCPorter (github.com/steipete/mcporter) | Converts MCP tools to CLI commands. Describes MCP as "a crutch" for environments without terminal access. |
Token Cost Breakdown
The ScaleKit benchmark reveals why CLI wins for agent consumption:
| Metric | CLI | MCP |
|---|---|---|
| Schema overhead per turn | 0 tokens (agent calls --help on demand) |
500-2000 tokens (full tool definitions injected every turn) |
| Output shape | Agent requests exactly what it needs via flags | Full JSON-RPC response, unfiltered |
| Composition | Piped through jq, grep, mlr |
Atomic calls only |
| Failure mode | Exit code + stderr message | ConnectTimeout to MCP endpoint (36% of MCP failures) |
The gap grows with tool count. A CLI aggregate (one binary with subcommands) costs ~100 tokens in --help output. An MCP aggregate costs ~43 tool schemas × ~500 tokens each = ~21,500 tokens per turn.
Decision Framework
| Situation | Default | Rationale |
|---|---|---|
| Agent already has a terminal | CLI | No bridge needed. Agent pipes output directly. |
| Single-user, personal/homelab | CLI | Simpler to build and debug. No server to maintain. |
| Multi-tenant, end-user OAuth | MCP | Auth delegation and credential management handled by the protocol. |
| Token-sensitive at scale | CLI | 9-32× cheaper per operation. |
| Need composability (pipes) | CLI | `cmd |
| Need dynamic resource discovery | MCP | MCP's list_resources + subscribe provides real-time schema discovery. |
| Enterprise audit/traceability | MCP | JSON-RPC has structured request/response logging at the protocol level. |
| Internal bespoke API | Either — CLI with --json is simpler; MCP if governed access is required |
Bottom line: CLI is the default for most agent-facing tools. MCP wins for governed multi-tenant deployments where credential management and audit trails are the primary value. In practice, many deployments end up hybrid: CLI for high-frequency known tools, MCP for sandboxed or governed integrations.