MCP vs API vs Skills vs CLI: when to use each one

Use a CLI when the system already has a command line and you are logged into it; a direct API call for one-offs or your own script; MCP when there is no CLI, when several clients or agents need the same access, or when authentication should not live in the shell. A Skill connects to nothing: it teaches the agent which of those paths to use and how, and usually sits on top of a CLI or an MCP server.

MCP, API, Skill and CLI show up in the same discussions, but they are not four options of the same kind. Three are ways for the agent to reach a system; a Skill is a way to teach the agent how to use what it reaches. Below, the same task (listing a GitHub repository's open issues) done all three ways on Claude Code 2.1.300, a Skill that ties it together, and a decision table.

What is the difference between MCP, API, Skill and CLI?

Option	What it is	Who handles auth and format
CLI	An existing program (`gh`, `aws`, `psql`) the agent calls through Bash	The CLI itself, with the login you already did
API	A direct HTTP request (`curl` or a script)	You: token, pagination, rate limits
MCP	A server that exposes typed tools to any MCP client	The MCP server
Skill	A SKILL.md with instructions and procedure, loaded on demand	Nobody: a Skill connects to nothing

The Claude Code docs put it this way: MCP connects Claude to external services; Skills extend what it knows, including how to use those services. That is why "MCP vs Skill" almost always ends up as "MCP + Skill".

What does the same task look like through the CLI?

If gh is installed and logged in, the agent needs nothing else. It is the lowest-setup path:

$ gh issue list -R anthropics/claude-code --state open --limit 3 --json number,title
102375 [FEATURE] Feature request: periodic lightweight context audit (...)
102374 [BUG] Desktop (Windows): session worktree creation fails with (...)
102373 [BUG] Remote Control: Artifact delete confirmation renders only (...)

The cost: the output lands whole in the context, and the agent has to know the flags. Asking for --json with only the fields you need helps with both.

And through the API directly?

Same numbers, nothing installed beyond curl:

$ curl -s "https://api.github.com/repos/anthropics/claude-code/issues?state=open&per_page=3"
# JSON with the same 3 numbers: 102375, 102374, 102373

$ curl -sI https://api.github.com/repos/anthropics/claude-code | grep -i x-ratelimit-limit
x-ratelimit-limit: 60

Without a token, the GitHub REST API allows 60 requests per hour (the header above). With a token, you own where it is stored, pagination and errors. A direct API call suits one-off calls or your own script; as the agent's standing interface, it pushes onto you work a CLI or an MCP server already does.

And through MCP?

GitHub's remote MCP server exposes tools such as listing issues and opening PRs, authenticated by a token in a header. Adding it without the header fails at connect time:

$ claude mcp add --transport http github https://api.githubcopilot.com/mcp/
$ claude mcp list
github: https://api.githubcopilot.com/mcp/ (HTTP) - ✘ Failed to connect — Incompatible auth server: does not support dynamic client registration

# with the .mcp.json above, in project scope:
$ claude mcp list
github: https://api.githubcopilot.com/mcp/ (HTTP) - ⏸ Pending approval (run `claude` to approve)

What works is the server's official guide: a personal access token in the Authorization header. In the project's .mcp.json, use an environment variable instead of the literal token, so the file can go into git:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_PAT}" }
    }
  }
}

A project-scope server stays pending until you approve it in a claude session, as the second output shows. Scopes, approval and variables are covered in how to configure MCP in Claude Code.

MCP pays off when the same access has to serve several clients (Claude Code, Claude Desktop, another agent) or when the system has no CLI. Per the MCP docs, tools load only their names at session start and the full schema on demand, so an idle server costs little context.

Where does the Skill come in?

A Skill replaces none of the three. It says which path to use and how. This one picks the CLI, limits Bash to gh issue list and sets the answer format:

---
name: open-issues
description: Lists and summarizes a GitHub repository's open issues. Use when asked to triage, summarize or count issues.
allowed-tools: Bash(gh issue list *)
---

To list issues, run gh (do not call the API by hand):

    gh issue list -R <owner>/<repo> --state open --limit 20 --json number,title,labels

Group by label and return a short table: number, title, label.
If gh is not authenticated, say so and stop.

$ claude plugin validate .claude/skills
Validating components in: .../.claude/skills

✔ Validation passed

SKILL.md structure, allowed-tools and arguments are in the walkthrough on how to create a Claude Code Skill.

When should you use each one?

Situation	Use
The system has a good CLI and you are already logged in	CLI
A one-off call, or a script you already maintain	Direct API
No CLI, or the same access serving several clients and agents	MCP
Auth and permissions that should live neither in the prompt nor the shell	MCP
The agent gets the procedure, format or step order wrong	Skill (on top of CLI or MCP)
A rule that must always hold, regardless of the model	A hook, not a Skill

Start with the CLI when there is one. Move to MCP when a second client shows up or when the token cannot live in the shell. Write the Skill the third time you explain the same procedure in chat.

What was tested here

gh issue list and curl against GitHub's public API on 2026-10-15: the same 3 issue numbers, and x-ratelimit-limit: 60 without a token.
claude mcp add without a header (connection failure above) and the .mcp.json with ${GITHUB_PAT} (pending approval), on Claude Code 2.1.300. Connecting with a valid token was not tested.
claude plugin validate on the Skill folder: passed. Invocation in a logged-in session was not tested.

Frequently asked questions

Does MCP replace APIs?▼

No. An MCP server usually calls the API underneath. MCP standardizes how the agent discovers and calls those operations, and where authentication lives.

Skill or MCP?▼

MCP when you need to connect to a system; Skill when you need to teach a procedure. Often both together.

Why not just use the CLI?▼

Often you can. The CLI stops being enough when the system has none, when other clients need the same access, or when you do not want the token in the agent's shell environment.

Does MCP use a lot of context?▼

Less than it used to: Claude Code loads tool names at start and the schema only when needed. Run /context to see each server's weight and turn off the ones you do not use.