Claude Code API vs MCP vs CLI: which should you use?
API gives exact control, CLI packages a stable command, and MCP adds tool discovery. Use this matrix to choose the right Claude Code connection.
Choose a direct API when you need an exact request inside an application, a provider CLI when one stable command already does the job, and MCP when discoverable tools make the connection easier to reuse. A CLI does not replace MCP, and MCP does not replace APIs. The right choice is the narrowest trusted interface that makes your task inspectable and repeatable.
This site is independent and is not affiliated with Anthropic. Product behavior and primary sources in this guide were checked on July 12, 2026.
First, separate three different layers
An external service API is the request-and-response contract for a service such as Google Drive.
The Claude API sends messages to a Claude model. It does not automatically connect that model to Drive or Slack. If Claude requests a client tool, your application executes the outside operation and returns the result. Anthropic's tool-use documentation shows that round trip.
The Claude Agent SDK sits higher up. It supplies an agent loop, tool execution, sessions, permissions, hooks, and cost controls. Anthropic distinguishes it from ordinary Claude API clients, which send and handle individual requests.
Here, CLI means a service provider's command-line tool called through Bash, not the claude executable. Claude Code's non-interactive claude -p mode is a separate runtime choice for scripts and CI. It can still use a direct API wrapper, a provider CLI, or an MCP server. Anthropic's programmatic usage guide recommends --bare for scripted runs; bare mode skips automatic MCP discovery unless you pass a configuration explicitly.
Claude Skills package a procedure; they do not create a connection or grant access.
API vs CLI vs MCP at a glance
All three routes may reach the same upstream API. All three may read or write if the credential and exposed operation allow it. The interface name is not a safety guarantee.
| Question | Direct external API | Provider CLI through Bash | MCP server |
|---|---|---|---|
| Authentication | Provider key, OAuth, service account, or workload identity | Usually the provider's own credentials and scopes | Remote OAuth or server-specific credentials; local servers often use environment variables |
| Read or write | Either, depending on endpoint and scope | Either, depending on command and scope | Either, depending on exposed tool and scope |
| Context cost | Request instructions and returned data use context | Help text, command, and output use context | Tool schemas, calls, and results use context; tool search can defer schemas |
| Determinism | A pinned request can be exact | A pinned command and flags can be exact | A tool implementation can be exact |
| Portability | The HTTP contract travels, but your code and auth remain | Depends on binary, operating system, version, and auth | MCP is a standard, but clients, transports, and auth still differ |
| Maintenance | You own code, retries, validation, and API changes | Maintainer absorbs some API changes; you own versions and command changes | Server maintainer owns the adapter; you own trust, configuration, and compatibility |
| Observability | HTTP status, request IDs, logs, and tests if you build them | stdout, stderr, exit code, and sometimes JSON or dry-run | Named tool calls and results in Claude Code; server logs depend on the implementation |
MCP's main advantage is discovery. Its protocol lets a server expose tools, resources, and prompts through a standard client-server structure, as the MCP architecture guide explains. Claude can discover a relevant tool instead of you teaching it every endpoint.
The transport and authorization still matter. Claude Code recommends HTTP for remote cloud servers, while stdio runs a local process. A remote server may use OAuth or another HTTP credential; a local server commonly receives credentials through its process environment. MCP standardizes discovery and invocation, not the upstream provider's identity, scopes, or authorization policy.
If credential setup is the unfamiliar part, use the API key and .env safety guide before connecting a service.
Choose the interface in six steps
Name one operation
Choose list five Drive files, not connect all of Google Workspace.
Choose the identity and scope
Use a test account and the narrowest provider permission that can complete that operation.
Inspect the owner and support status
Check current first-party docs, releases, auth method, and maintenance warnings.
Pick the smallest surface
One stable command may beat a new server; a trusted MCP server may beat maintaining many wrappers.
Require visible evidence
Bound the result, prefer structured output, and retain the status, exit code, or tool result.
Package it only after it works
Once the manual path is proven, a Skill can preserve the procedure without becoming the connection.
This is context engineering: choosing the tools, rules, and result shape Claude needs. The Claude Code context engineering guide covers that wider information design.
A fair read-only Drive comparison
Here is a reproducible experiment for this choice. It is a proposed test, not a result: we have not run and preserved both conditions, so this guide does not claim that either route wins.
The task is to list at most five Google Drive files, ordered by most recently modified, returning only id, name, mimeType, and modifiedTime. Use a disposable test account and Google's drive.metadata.readonly OAuth scope. Google's Drive scope documentation defines it as metadata viewing, not file-content download or modification. Google classifies it as restricted, so this test is not a shortcut for designing a public OAuth application.
For the CLI condition, pin a release of Google's gws tool. Treat this as a candidate command and verify it against that release's current schema before running:
gws drive files list --params '{"pageSize":5,"orderBy":"modifiedTime desc","fields":"files(id,name,mimeType,modifiedTime)"}'
For the direct API condition, make the equivalent current files.list request:
GET https://www.googleapis.com/drive/v3/files
?pageSize=5
&orderBy=modifiedTime%20desc
&fields=files(id,name,mimeType,modifiedTime)
Authorization: Bearer [REDACTED]
Use the same short-lived token, account, model, prompt, result limit, and Claude Code permission mode. Record setup time separately from execution. Capture the returned fields, approval count, HTTP status or exit code, errors, elapsed time, and number of turns.
The upstream gws repository documents structured JSON, schema inspection, and pre-obtained access tokens. It also says the project is not an officially supported Google product, remains under active development, and may change before v1.0.
Do not add a random community MCP server merely to create a third condition. A fair MCP run needs a server you trust, equivalent read-only authorization, a reviewed implementation, and the same output boundary. Claude connectors explains why a reviewed directory connector and an unreviewed custom server carry different trust assumptions.
What this experiment would not prove
One Drive task cannot prove that every CLI is faster, every API is easier to audit, or MCP always consumes more tokens. Setup depends on credentials you already have. Output size, retries, schemas, and model decisions change context use.
Current Claude Code MCP documentation says tool search is enabled by default in supported setups. It defers MCP tool definitions until Claude needs them, so adding a server no longer implies one fixed context penalty. Used schemas, calls, and results still consume context.
Determinism also stops at the interface boundary. A pinned request or command can behave predictably, while Claude's decision about which command to call, which records matter, or what the response means can still vary. For a large investigation with disposable reading, a focused subagent may protect the main context, but it does not make the integration deterministic.
For sensitive work, use the provider's least-privilege scope plus Claude Code's technical permission controls. Anthropic's permissions guide warns that broad Bash prefix rules are fragile. Avoid treating Bash(gws *), a tool name, or reassuring prompt language as a policy-grade boundary.
Does MCP replace APIs?
No. An MCP server commonly calls an upstream API itself. MCP standardizes how an AI client discovers and invokes exposed capabilities; the service API still defines the underlying data and operations.
Is MCP more expensive in tokens?
It depends. Tool definitions, calls, and results use context, but Claude Code now defers MCP definitions with tool search in supported default setups. Large CLI or API output can also consume substantial context.
Should Claude Code use a CLI or MCP?
Use a trusted CLI for a narrow repeatable command with structured output. Prefer MCP when discovery across several tools makes the extra server and trust surface worthwhile. For production software needing exact handling and tests, consider the direct API.
The durable rule is simple: choose the path that makes one needed operation narrow, authorized, observable, and repeatable. The logo on the interface matters less than the evidence it leaves behind.