Skip to content
agents.cli

MCP servers

The agent is brilliant at the code. It knows your language, your patterns, your test framework. You ask it to “close out the auth bug ticket once the fix is in,” and it doesn’t know what a ticket is. You ask it to “check what tickets are blocked on the migration” and it can’t see Jira at all. You ask it to “pull the current pricing from the staging DB to test against” and it has no way to reach the database.

So you do what you always do: you switch tabs, open Jira, copy the ticket title, paste it back. Open a SQL client, run the query, paste the rows back. Hit Figma, screenshot a frame, drop it in. The agent does the coding; you are the integration layer to everything else. Every external system is a context switch you pay for.

The Model Context Protocol (MCP) takes you out of that loop. MCP is an open wire format for connecting an AI tool to an external service - a database, a browser, a ticket tracker, a file store, a search index.

An MCP server is a typed adapter that exposes one of those systems as a set of tools (e.g. jira.search_issues, postgres.query, figma.get_node); the CLI is the client that discovers them at startup and lets the model call them as if they were built in. Now the agent itself runs jira.get_ticket("AUTH-412"), sees the result, and acts on it - the integration moves from “you, by hand” to “the agent, in-flow.”

All six tools in scope are MCP clients. Pi is the newest: it shipped built-in MCP support in 0.99.0 (September 2026) after launching without it.

Real-world examples of MCP servers people actually run:

  • Issue trackers - Jira, Linear, GitHub Issues. The agent reads the ticket it’s working on, posts updates, closes it on merge.
  • Databases - Postgres, MySQL, SQLite. “Check the actual schema before you write this query.” No more guessing the column name.
  • Browser automation - Playwright/Puppeteer. The agent navigates a staging site, fills a form, screenshots the result to verify a UI change.
  • Cloud consoles - AWS, Cloudflare, Vercel. List buckets, check deployments, read logs without leaving the session.
  • Design tools - Figma. The agent reads the actual component spec instead of you describing it.
  • Search & knowledge - Notion, Confluence, internal vector stores. The agent looks up the runbook on its own.
  • Filesystem at scale - large data lakes, S3, object stores. Beyond what local Read/Glob can reach.

The test: if the answer to “why did you do it that way?” is “I had to guess because I can’t see the source,” there’s probably an MCP server that closes the gap.

Watch the 2-minute version

MCP servers. Watch on YouTube

What MCP actually is

Section titled “What MCP actually is”

MCP is a protocol - a wire format - with three architectural roles:

MCP host
(your AI CLI or app)
owns user consent and policy
contains one or more clients
stdio / HTTP →
"list_tools" →
← [search_issues, get_issue, …]
"call_tool search_issues(…)" →
← {issues: […]}
MCP client
(connection inside the host)
maintains the protocol session
exposes server capabilities to the host
stdio / HTTP →
"list_tools" →
← [search_issues, get_issue, …]
"call_tool search_issues(…)" →
← {issues: […]}
MCP server
(jira, postgres, figma, your own…)
exposes prompts, resources, and tools
serves context or runs calls against a real system

Note how little the server panel commits to. Anything that speaks the protocol qualifies as a server: a tiny stdio binary, a remote HTTP service, a one-off Python script you wrote this morning. The server can expose three different kinds of capability: prompts (user-controlled templates), resources (application-controlled context), and tools (model-controlled actions). That is the entire bar for entry.

Three things follow from this shape, and they explain most of the per-tool quirks below:

  • Discovery is dynamic. The server defines what tools exist. Change the server, you change the agent’s surface area without changing the CLI.
  • Cost can land in the context window. A client may put registered tool definitions in the model’s context immediately, defer schemas until use, or apply its own search/indexing layer. A server exposing 60 tools can therefore become a 60-tool tax, depending on the host - which is why /mcp commands exist to inspect what each server is costing you.
  • Which side you’re on. Most tools in scope are MCP clients only. Claude Code can also be a server over stdio: claude mcp serve offers Claude Code’s own primitives - Bash, Read, Edit, Write, WebSearch, Agent and the rest - so the caller keeps the reasoning and borrows the toolbox. Codex used to offer the opposite shape, codex mcp-server with codex and codex-reply tools that ran a whole Codex turn, but the command has been removed; integrations now use the Codex app server, which speaks its own JSON-RPC protocol rather than MCP. And don’t read a serve subcommand as MCP by default, because opencode serve starts OpenCode’s own HTTP API, not an MCP endpoint.

The unusual property of MCP - and the reason it spread fast - is that the client and server are decoupled. The Jira MCP server you wrote for Claude Code works in Codex, OpenCode, Cursor, and Copilot unchanged. Compare with skills, which needed a published spec before other tools could converge on SKILL.md - MCP was a shared protocol from day one, with no spec-publication moment to wait for.

What your servers cost you

Section titled “What your servers cost you”

The second consequence is the one you can put a number on. Toggle servers on and off and watch the window fill before you have typed a single message - then flip on schema deferral to see why it exists.

82k of 200k (41%) spent before your first message
Built-in tools (12k, fixed)MCP tool schemas (70k)

Tool counts and schema sizes are illustrative (~600 - 800 tokens per tool definition). The shape is the point: every enabled server's schemas are paid for in window space - up front on clients that load eagerly, at first use on clients that defer.

Why this and not…

Section titled “Why this and not…”
You want to… Reach for Not
Connect the agent to a real external system MCP server Skill describing the system
Encode procedures or institutional knowledge Skill MCP server
Inject the same context every session Rules MCP server
Restrict what tools the agent can call Permissions MCP-server choice alone
Run a side effect on every tool call Hook MCP server
Bundle and distribute a server + skills + commands Plugin Raw MCP install

MCP is about reach - letting the agent touch systems outside the CLI. Skills, memory, and hooks are about behaviour. If you’re trying to teach the agent what to do, you want a skill. If you’re trying to give the agent something to act on, you want an MCP server.

How it works in each tool

Section titled “How it works in each tool”

Showing: Claude Code pick a tab to change

Configuration: .mcp.json at the project root, or claude mcp add to register from the CLI. Servers can be scoped:

  • Local (default) - stored in ~/.claude.json under the current project, private to you
  • Project - .mcp.json checked into the repo, shared with your team
  • User - registered via claude mcp add --scope user, available across all your projects

Precedence (most-wins): managed or CLI configuration > local > project > user, subject to the current Claude Code configuration rules.

Inspect and manage: /mcp in-session shows connected servers, available tools, and current health. MCP connections can fail mid-session - use /mcp if Claude stops being able to use a tool it had access to earlier.

Claude Code as an MCP server: claude mcp serve runs Claude Code itself as an MCP server over stdio, exposing its own primitives - Bash, Read, Edit, Write, WebSearch, Agent, Skill and the rest - as tools any MCP client can call. Note the direction: claude mcp add registers a server Claude Code calls, while claude mcp serve makes Claude Code the thing being called.

Tool search is on by default where supported - idle MCP tools usually consume minimal context until used. Providers, gateways, and unsupported models can fall back to loading definitions up front, so check the current MCP documentation before promising a fixed token cost.

Comparison

Section titled “Comparison”
Aspect Claude Code Codex OpenCode Cursor Copilot Pi
Config file .mcp.json ~/.codex/config.toml opencode.json .cursor/mcp.json .vscode/mcp.json (deprecated in VS Code’s guided flow; ~/.copilot/mcp-config.json is the global file) ~/.pi/agent/mcp.json (user), .pi/mcp.json (project)
Scopes local / project / user / managed user (~/.codex/) / project (.codex/) / managed global / project / managed project / user workspace / user / org user / project
Inspect command /mcp /mcp /mcp /mcp list, /mcp list-tools - /mcp, pi mcp list
Transports stdio, HTTP (streamable-http), SSE (deprecated) stdio, streamable HTTP local (stdio), remote (HTTP) stdio, SSE, streamable HTTP stdio, HTTP, SSE stdio, streamable HTTP (SSE rejected)
Can be an MCP server Yes (claude mcp serve) No (codex mcp-server was removed; the app server is a separate protocol) No No No No
Tool search (lazy schemas) Availability and thresholds are version/configuration-dependent - - - - Built-in tool_search and codemode extensions
LSP servers as first-class No (LSP via MCP if at all) No Yes (diagnostics into agent context) - - -
One-click install - - - “Add to Cursor” deep link MCP Registry browser -
OAuth for remote servers Yes Yes Yes Yes (fixed redirect URL) Yes (VS Code); - (cloud agent) Yes (/mcp login)

Name collisions

Section titled “Name collisions”
  • “MCP” specifically refers to the Model Context Protocol. Don’t confuse with generic “plugins” - see Plugins & marketplaces for distribution-layer packaging.
  • Claude Code holds a dual MCP role - consumer and producer - so “an MCP server” in its conversation can mean something the tool calls or the tool itself. claude mcp add registers a server Claude Code calls, while claude mcp serve turns Claude Code into one. Codex dropped its producer role when codex mcp-server was removed, so codex mcp now only manages servers Codex calls.
  • Copilot’s MCP surface spans VS Code Chat agent mode, the cloud agent, and the CLI - they share the protocol but not the config schema or capabilities. The IDE story (VS Code Chat, .vscode/mcp.json) is what this chapter focuses on.

The next server you install, install it and then measure it. Claude Code, Codex, OpenCode, and Pi all answer /mcp with the servers currently connected, including ones that have quietly died mid-session. For the token side of the question in Claude Code, /context is the view that breaks down what’s occupying the window; /mcp answers connection state, not cost. A server whose schema tax outweighs how often the agent actually calls it is the one to drop - or the one to leave to tool search rather than keep resident.