Jonathon's AI Wiki

MCP — Model Context Protocol

6 min read

Source: wiki synthesis: essential-mcp-servers, nate-herk-every-level-of-claude, cli-vs-mcp-tool-selection

MCP (Model Context Protocol) is Anthropic’s open protocol for connecting LLMs to external tools, data sources, and systems through a uniform JSON-RPC interface. The specification lives at modelcontextprotocol.io and is implemented by both Anthropic and a growing list of third-party LLM clients. MCP is the standard interface that lets one server (e.g., GitHub, Playwright, Sentry, Postgres) plug into many different agent harnesses without per-client glue code ^[inferred].

Key Takeaways

  • Open protocol, not a product. MCP is a spec maintained at modelcontextprotocol.io; anyone can implement either side. Anthropic shipped it, but it is not Anthropic-only — Cursor, Zed, Cowork, Claude Desktop, Claude Code, and other clients all speak it.
  • Two-sided architecture. MCP servers expose tools, resources, and prompts from a system (GitHub, a database, a browser). MCP clients are the LLM-side runtimes that connect to those servers and decide which tools to invoke. The same server works across every conforming client ^[inferred].
  • Distinct from Connectors. connectors are pre-built, Anthropic-managed MCP servers (50+ — Slack, Gmail, Drive, Notion, GitHub, Calendar) that ship with one-click OAuth inside claude.ai. Generic MCP is the underlying protocol; Connectors are a curated, hosted subset.
  • Supplements raw tools, doesn’t replace them. MCP is the right surface when state, auth, or org-level controls are involved; CLI commands remain better for file ops, Git, and text processing the model already knows from training (see cli-vs-mcp-tool-selection).
  • Ecosystem breadth. The community has shipped hundreds of public MCP servers across GitHub ops, documentation lookup, browser automation, observability, databases, and design tools — see essential-mcp-servers for the high-value starter set.
  • Context-aware by design. Claude Code’s Tool Search loads MCP tool schemas on demand instead of at session start, cutting upfront context overhead by ~95% — making it safe to keep 10+ servers configured.
  • Three configuration scopes. User (global), local (per-project, uncommitted), and project (.mcp.json, committed) — letting teams share essential servers via Git while keeping personal preferences separate.

How MCP works

MCP is a JSON-RPC protocol that runs over two transports:

  • stdio — the client launches the server as a subprocess and exchanges JSON-RPC messages over stdin/stdout. Used for local servers (filesystem, git, sequential-thinking).
  • HTTP / streamable-http — the client connects over HTTP to a remote endpoint. Used for hosted servers (https://mcp.draw.io/mcp, Railway Remote MCP, Cloudflare-Workers-deployed servers). streamable-http and http are equivalent type: values in .mcp.json.

Each server exposes three primitive types:

  • Tools — callable functions with a JSON schema describing inputs and outputs. The model picks tools to invoke based on the schema’s description.
  • Resources — readable data sources the model can request (files, documents, query results) addressed by URI.
  • Prompts — server-provided prompt templates the client can surface to the user as slash commands or quick actions.

Connection setup is a capability-negotiation handshake: the client announces the protocol version and supported features, the server responds with its tool/resource/prompt list and any server-specific options (e.g., _meta.anthropic/maxResultSizeChars to raise the per-tool result-size cap up to 500K characters). Because the handshake is transport-agnostic, the same server binary works across every conforming MCP client ^[inferred] — the major harnesses (Claude Code, Cowork, Claude Desktop, Cursor, Zed) all implement the client side, so a Postgres MCP server you wrote for one runs in all of them unchanged.

MCP vs CLI tools (when to choose which)

See cli-vs-mcp-tool-selection for the worked-exercise deep dive. The short version:

  • Reach for CLI when the operation is structured, token-cheap, and the model already knows the command from training data (git log, grep, curl, cat, file ops). CLI composes via pipes; MCP tool calls do not. Anthropic’s own docs say: when a CLI exists, prefer it — GitHub / AWS / Google Workspace CLIs use ~60-70% fewer tokens than the equivalent MCP servers because no schema is loaded until the command runs.
  • Reach for MCP when there’s a capability gap raw tooling can’t bridge (fetching a JS-rendered Next.js page), when authentication is server-managed (OAuth for Slack/Notion/databases), or when org-level controls (per-user access, audit trails) matter.
  • The diagnostic anti-pattern: if the agent starts reverse-engineering a JavaScript framework just to read a web page, it picked the wrong surface — MCP would have closed the gap in one tool call.

Recent additions (2026-06-28 watchlist sweep)

New MCP client features in Claude Code as of v2.1.186–v2.1.193, sourced from ai-research/watchlist-snapshots/code-claude-com-docs-en-mcp-2026-06-28.md:

  • claude mcp login / mcp logout (v2.1.186) — Authenticate or clear credentials for a configured MCP server directly from your shell, without entering the interactive /mcp menu in a running session. Useful for servers requiring OAuth (e.g., GitHub MCP, Slack MCP): run claude mcp login <server-name>, complete the auth flow in your browser, and credentials persist for subsequent sessions. claude mcp logout <server-name> clears stored credentials.
  • list_changed — dynamic tool registration — Servers that declare the list_changed capability can add or remove tools during a session without restarting. Claude Code subscribes to tool-list change notifications and updates its available tool set on the fly. Enables servers that lazily register tools after an OAuth handshake completes or after discovering project context.
  • Automatic reconnection with exponential backoff — Claude Code automatically reconnects to MCP servers after disconnection (network drop, server restart). Reconnection is transparent and does not require restarting the session.
  • 5-minute idle timeout (CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT) — MCP servers not called for 5 minutes are marked idle. Override with CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT=<seconds> in your environment or settings.json. Useful when a server has expensive startup cost and you want to keep it warm for longer.

Try It

  1. Inspect your current setup. Look at .mcp.json in your project root and ~/.claude/ for user-scope config. Run /context in Claude Code to see how much of your context window MCP schemas are consuming.
  2. Start with the highest-ROI server. If you have zero MCP servers configured, add GitHub MCP first — repository operations cover the most common cases. Add Context7 to user scope for documentation lookup across every project.
  3. Apply the decision rule to every server you’ve enabled: does the model already know how to do this from CLI knowledge it has from training? If yes (local git, local filesystem), the server may be net-negative on context. If authentication, state, or org controls are involved (Slack, Notion, Postgres), the schema cost almost always pays for itself.

Graph View

Backlinks