← All guides
Guides November 1, 2026

MCP vs CLI vs API Explained: What Your Agent Should Use

In 2025 the advice was to wrap everything in an MCP server. In 2026, engineers started to measure, and the CLI often won on tokens. Then the MCP spec changed, tool search arrived, and the argument turned again. The real answer is not one winner. Each of the three is the right tool for a different job. This guide gives the numbers, the rule, and where each one lives in OpenClaw.

Bottom Line

  • All three can do the same job. “List my open pull requests” works with GitHub’s MCP server, with gh pr list, or with one HTTP call.
  • The CLI is usually the cheapest when the model already knows the tool. One benchmark measured 32x fewer tokens than MCP on a task.
  • MCP is the best fit when no good CLI exists, when you need OAuth per user, or when you want a short list of allowed actions.
  • A direct API call is the best fit when you own the integration. Wrap it as one tool and keep the key out of the model’s sight.
  • Tool search removes most of MCP’s token cost. Turn it on before you judge MCP by its token bill.

The Rule

UseWhenWhy
CLIThe model already knows it (gh, aws, git, kubectl) and the agent has a shellFew tokens, output pipes through jq and grep, the auth already exists
MCPNo good CLI, a SaaS app, a team setup, or OAuth per userStandard discovery, standard auth, a fixed list of actions
APIYou own both sides and want an exact contractSmallest surface, no extra process, full control of inputs

The question of skills is a different split. A skill is a procedure, not an ability. Our MCP vs skills page covers it.

The Token Cost

Why MCP costs tokens before work starts

Most MCP clients load every tool definition into the context at the start. Anthropic’s November 2025 example had five servers:

ServerToolsTokens
GitHub35About 26,000
Slack11About 21,000
Sentry5About 3,000
Grafana5About 3,000
Splunk2About 2,000

That is about 55,000 tokens of definitions, before the first message. Anthropic says it has seen tool definitions reach 134,000 tokens.

What the CLI benchmarks show

Scalekit (March 2026) ran Claude Sonnet 4 on 5 read-only GitHub tasks, 75 runs, with GitHub’s official MCP server (43 tools) against the gh CLI:

TaskCLI tokensMCP tokensRatio
Repo language and license1,36544,02632x
Latest release and dependencies8,75037,4024x

The CLI also finished more often: 25 of 25 runs, against 18 of 25 for MCP. All 7 MCP failures were connection timeouts.

Read it with care. The sample is small, and Scalekit sells auth products. Its own conclusion is that MCP is still needed for multi-user auth.

Eric Holmes’s post “MCP is dead. Long live the CLI” (February 2026) gives the reasons. Models learned CLIs from years of man pages and scripts. CLI output pipes through other tools. And gh pr view can be allowed while gh pr merge asks first.

Tool search changes the math

The fix for MCP’s token cost is to load tool definitions only when the agent needs them. This is tool search. The agent sees a search tool, looks up what it needs, and only those definitions enter the context.

MeasureWithout tool searchWith tool search
Context used before work (Anthropic example)About 77,000 tokensAbout 8,700 tokens
Opus 4 accuracy on Anthropic’s MCP evals49%74%
Opus 4.5 accuracy79.5%88.1%

Anthropic’s docs say tool choice gets worse after 30 to 50 tools. More tools in the context make the agent pick worse, not only cost more.

Where tool search is today:

  • Claude Code: on by default for MCP tools (ENABLE_TOOL_SEARCH, auto starts at 10% of the context window).
  • Claude API: defer_loading: true on tools, up to 10,000 deferred tools.
  • OpenAI API: a tool_search tool with defer_loading, on gpt-5.4 and later.
  • OpenClaw: tools.toolSearch, on by default for some run types. It is marked experimental.

One estimate on Hacker News put an 84-tool setup at about 15,540 tokens with plain MCP, about 500 with tool search and about 300 with a CLI. With tool search, most of the gap is gone.

What Changed in MCP in 2026

The MCP spec version 2026-07-28 is the biggest change since launch. Simon Willison wrote that it “recaptured” his interest.

ChangeWhat it means
No more sessionsThe Mcp-Session-Id header is gone. Each request stands alone
No initialize handshakeEach request carries its version and client abilities
Tasks moved to an extensionLong-running jobs use io.modelcontextprotocol/tasks, with polling and mid-job input
Fixed tool orderServers should list tools in a fixed order, for better prompt cache hits
Sampling, Roots and Logging deprecatedFewer features for clients to build

Two more items people often attach to this release came at other times:

  • MCP Apps (interactive UI in a sandboxed iframe) was already an extension, with a spec dated January 2026.
  • The Skills extension for MCP went final on 13 September 2026, about six weeks later.

Stateless MCP is easier to run. A server is now closer to a normal web API behind a load balancer. That removes a common reason teams preferred a plain API.

Security: Who Holds the Keys

This is where the three differ most.

CLIMCP (remote)API wrapped as a tool
Where the credential isYour shell login (gh auth, ~/.aws)An OAuth token per server, refreshed by the clientWherever the tool code reads it
What the agent can reachEverything that shell login can reachThe actions the server exposesThe one action you wrote
Per-user authHard. All users share one loginBuilt in (OAuth 2.1)You build it
Easy to auditHard. Any command is possibleEasier. A fixed list of toolsEasiest

Three facts from the sources:

  • MCP auth is optional. A local stdio server reads credentials from its environment, like a CLI. The OAuth rules apply to remote HTTP servers.
  • Remote MCP servers must not pass your token through to other services. The spec forbids it.
  • A shell is a large surface. Willison’s view: MCP tools are easier to audit than a shell with network access.

A CLI gives the agent your full login. If the agent reads a poisoned web page, an injected gh repo delete is one command away. Our local LLM prompt injection guide covers this risk.

Where Each Lives in OpenClaw

PathOpenClaw featureSettings and commands
MCP clientConnect OpenClaw to other MCP serversmcp.servers.<name> with command/args (stdio) or url, transport, auth: "oauth". toolFilter.include/exclude limits the tools
MCP serverExpose OpenClaw to Claude Code and other clientsopenclaw mcp serve
CLIThe exec tooltools.exec.mode: deny, allowlist, ask, auto, full
Managed gh loginA separate GitHub identity for the agenttools.github
API as a toolA plugin toolapi.registerTool in a plugin
Keys out of contextThe secrets tool asks for a credential the agent never seesOn by default
Tool searchLoad tool definitions on demandtools.toolSearch

A short example that adds a remote MCP server and keeps only the read tools:

openclaw mcp add docs --url https://mcp.example.com/mcp --transport streamable-http --include 'search,read_*'
openclaw mcp doctor docs --probe

Two warnings from the OpenClaw docs:

  • exec is a mutating shell surface. Turning off the write and edit tools does not make exec read-only.
  • Exec approvals are not a per-user auth boundary. They decide which commands run. They do not limit which accounts those commands use.

A Decision Checklist

  1. Does the model already know a CLI for this? Use the CLI, with tools.exec.mode: "allowlist" or "ask".
  2. Will other people use this agent with their own accounts? Use MCP with OAuth.
  3. Is it your own service with 1 to 3 actions? Write one plugin tool that calls your API.
  4. Do you have more than about 10 MCP tools? Turn on tool search and filter the tools you do not need.
  5. Does the agent read untrusted content? Prefer the narrow option: MCP with a tool filter, or a plugin tool. Avoid a full shell.

Honest Caveats

  1. We did not run these benchmarks. The token numbers come from Anthropic, Scalekit and other public posts. The vendor posts sell related products.
  2. Token counts depend on the server. GitHub’s MCP server is large. A small server with 3 tools costs much less.
  3. Tool search in OpenClaw is experimental. Check tools.toolSearch in your version.
  4. MCP is still changing. Check the current spec before you build on a feature.

Sources

See Also

Read next

Context Rot Explained: Why Agents Get Worse Over Time
Context rot is the drop in model accuracy as the input grows, long before the context window is full. The benchmark data, why a 1M window is not 1M useful tokens, what compaction loses, and the fixes in Claude Code, the Claude API and OpenClaw.
Tool Search Explained: Why 100 Tools Make Agents Worse
Every tool you give an agent costs context and makes the right tool harder to pick. How tool search works (regex, BM25, embeddings), what it does to prompt caching, when code mode is better, and how to set it up in the Claude API, OpenAI and OpenClaw.
Quantization in Plain English: What Q4, Q5, Q8 Actually Cost You (2026)
Q4_K_M is the default sweet spot. Q8 is near-indistinguishable from FP16 at half the size. Below Q4 quality drops fast. A bigger model at Q4 usually beats a smaller model at Q8 — here is the plain-English version, plus UD/IQ/NVFP4 and KV cache quant.
MCP vs Skills for Agent Tools: Use This Rule
Use a skill for a repeatable workflow. Use MCP when the agent needs a new external capability. This guide shows where each boundary belongs.