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.”

Five of the six tools in scope are MCP clients; Pi is the exception, and deliberately so.

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.

What MCP actually is

MCP is a protocol - a wire format. There are exactly two roles:

MCP client

(your AI CLI)

discovers tools

exposes them to the model

stdio / HTTP →

"list_tools" →

← [search_issues, get_issue, …]

"call_tool search_issues(…)" →

← {issues: […]}

MCP server

(jira, postgres, figma, your own…)

exposes a typed set of tools

runs the call against the real system (Jira API…)

Note how little the right-hand 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. 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 lands in the context window. Every tool the server registers is a tool definition that has to live in the model’s context from startup, called or not. A server exposing 60 tools is a 60-tool tax on the window - which is why most CLIs in scope now defer MCP schemas until they’re used, and why /mcp commands exist to inspect what each server is costing you.
One side or the other. Most tools in scope are MCP clients only. Codex is the only one that can also be a server - exposing its own coding capabilities as tools that another agent (or another Codex) can call. When someone says “I’m using Codex over MCP,” ask which direction.

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

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)

Defer schemas until first use - each server shrinks to a ~0.4k stub (name + description); the full schema loads only when a tool is actually called. Claude Code ships this (tool search, on by default); the other tools in scope load schemas up front.

GitHub35 tools · 26kIssues, PRs, reviews, workflows - big surface, big schema.
Browser (Playwright)25 tools · 18kNavigate, click, fill, screenshot, network inspection.
Notion15 tools · 11kSearch, fetch, create and update pages and databases.
Figma12 tools · 9kRead frames, components, and design tokens.
Postgres8 tools · 6kQuery, schema inspection, explain plans.

Tool counts and schema sizes are illustrative (~600–800 tokens per tool definition). The shape is the point: every registered server is paid for in window space whether the session uses it or not.

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

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.

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.

Configuration: ~/.codex/config.toml with a [mcp_servers.<name>] table per server, or the codex mcp subcommand (codex mcp add, codex mcp login) to manage them from the CLI. Codex supports both stdio (local process via command/args) and streamable HTTP (url) transports.

Codex as an MCP server: the codex mcp-server subcommand runs Codex itself as an MCP server over stdio, exposing codex and codex-reply tools so another MCP client (Claude Desktop, Zed, the OpenAI Agents SDK, etc.) can drive it.

Inspect: /mcp in the TUI shows active MCP servers.

Configuration: the mcp field in opencode.json. Each server is declared with type: "local" (with a command array) or type: "remote" (with a url, plus optional headers and OAuth). MCP servers inherit OpenCode’s general config layering - project (opencode.json in the project root) merges over global (~/.config/opencode/opencode.json), with macOS-managed preferences and file-based managed settings taking precedence above everything else.

OpenCode also ships LSP server integration alongside MCP, configured via a separate lsp field in opencode.json. The agent receives LSP diagnostics as feedback while working in the codebase, without needing an MCP wrapper.

Configuration: mcp.json, resolved in priority order:

Project: <repo>/.cursor/mcp.json
User: ~/.cursor/mcp.json (also ~/.config/cursor/mcp.json on Linux)

The schema mirrors the common MCP shape: type, command, args, env, envFile for stdio; url and headers for remote. Variable interpolation works in command, args, env, url, and headers.

Transports: all three are supported - stdio (Cursor spawns and manages a local process), SSE (local or remote, Server-Sent Events), and streamable HTTP (local or remote).

One-click install: Cursor has a curated Marketplace in-app and a community directory at cursor.directory. An “Add to Cursor” button uses a deep link to write the server into the user’s mcp.json and trigger OAuth if needed.

OAuth: remote servers can use Cursor’s built-in OAuth flow; the redirect URL is fixed at cursor://anysphere.cursor-mcp/oauth/callback. Static OAuth client credentials can be embedded in mcp.json when the provider requires fixed Client IDs.

There is also an MCP Extension API for extensions to register MCP servers programmatically - niche, but it exists.

Configuration (VS Code Chat agent mode):

Workspace: .vscode/mcp.json (commit to repo to share with the team)
User: VS Code settings.json or a user-scope mcp.json
Install via: the MCP Registry browser, the --add-mcp CLI flag, the extensions marketplace (@mcp search), or hand-editing mcp.json
Auto-discovery of Claude Desktop configs via chat.mcp.discovery.enabled
Tool approval prompts fire on first use; auto-approve via chat.tools.terminal.autoApprove and friends

GitHub MCP Registry - a curated, one-click-installable server list browsable from inside the IDE.

Org policy: chat.mcp.access gates which servers can be used; Business/Enterprise admins can apply org-wide MCP policy.

Other surfaces (out of IDE scope, mentioned for completeness): GitHub documents MCP configuration for Copilot cloud agent and maintains a support matrix across Copilot surfaces in its MCP management documentation. Configuration schema and feature parity vary by surface; check the cloud-agent MCP documentation before assuming that an IDE or CLI setting transfers unchanged.

Pi has no native MCP support, and that’s deliberate. The whole design is four built-in tools - read, write, edit, bash - and everything else grows from bash, not from a growing list of first-class integrations. Adding an MCP client would cut against that minimalism.

What to do instead:

For most integrations, a CLI tool plus a skill or README covering how to call it gets you the same outcome through bash - no protocol layer needed.
If you specifically need MCP (e.g. to reuse an existing server you run for other tools), build or install an extension that adds an MCP client via the ExtensionAPI. This isn’t shipped by default - check the extensions ecosystem for whether one already exists before writing your own.
External bridges that translate MCP calls into shell invocations are another option if the server you need only speaks MCP.

If your workflow leans heavily on MCP servers today, this is the sharpest tradeoff to weigh before adopting Pi as your primary loop.

Comparison

Aspect	Claude Code	Codex	OpenCode	Cursor	Copilot	Pi
Config file	`.mcp.json`	`~/.codex/config.toml`	`opencode.json`	`.cursor/mcp.json`	`.vscode/mcp.json`	- (no native MCP)
Scopes	local / project / user / managed	user (`~/.codex/`) / project (`.codex/`) / managed	global / project / managed	project / user	workspace / user / org	-
Inspect command	`/mcp`	`/mcp`	`/mcp`	`/mcp list`, `/mcp list-tools`	-	-
Transports	stdio, HTTP (streamable-http), SSE (deprecated)	stdio, streamable HTTP	local (stdio), remote (HTTP)	stdio, SSE, streamable HTTP	stdio, HTTP, SSE	-
Can be an MCP server	No	Yes (`codex mcp-server`)	No	No	No	No
Tool search (lazy schemas)	Availability and thresholds are version/configuration-dependent	-	-	-	-	N/A
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); - (Coding Agent)	N/A

Name collisions

“MCP” specifically refers to the Model Context Protocol. Don’t confuse with generic “plugins” - see Plugins & marketplaces for distribution-layer packaging.
Codex’s dual MCP role - both consumer and producer - is unique in the foundations set, so “an MCP server” in a Codex conversation can mean either something Codex calls or Codex itself.
Copilot’s MCP surface spans VS Code Chat agent mode, the Coding 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, and OpenCode all answer /mcp with the servers currently connected; in Claude Code that view also breaks out token cost per server and flags connections that have quietly died mid-session. 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.