Jonathon's AI Wiki

MCP — Model Context Protocol

17 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

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
  • 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. Control behavior with ENABLE_TOOL_SEARCH (unset = full defer; auto = threshold-based; false = upfront load all). Use alwaysLoad: true on a per-server or per-tool basis to force a specific server’s tools into context at session start.
  • 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 three 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 (the MCP spec uses streamable-http; configurations copied from server docs work without modification).
  • WebSocket (type: "ws") — holds a persistent bidirectional connection; suited for remote MCP servers that push events to Claude unprompted. Use HTTP instead when your server only responds to requests (HTTP supports OAuth and claude mcp add --transport; WebSocket supports neither). Configure via claude mcp add-json or .mcp.json directly; the claude mcp add --transport flag does not accept ws.

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.

2026-07-28 spec revision

The MCP specification shipped its fifth and largest revision on 2026-07-28: a stateless protocol core — the capability-negotiation handshake and session model described under “How MCP works” above are retired in the new version — plus hardened OAuth/OIDC authorization, a formal twelve-month deprecation policy (Roots, Sampling, Logging, HTTP+SSE), and first-class extensions (MCP Apps, Tasks, Enterprise Managed Auth). Anthropic says support is rolling out across Claude products; the client behavior documented in this article reflects the pre-2026-07-28 protocol until that lands. Full coverage: MCP 2026-07-28 Spec — Stateless Core, First-Class Extensions, Auth Hardening. Sourced from raw/x-account-claudedevs-2082164248697069935.md and raw/reddit-1v97e2v.md.

Recent additions (2026-08-09 watchlist sweep)

New MCP client features from ai-research/watchlist-snapshots/code-claude-com-docs-en-mcp-2026-08-09.md:

MCP discovery cache (v2.1.221)

Remote MCP servers you have connected to before now show a cached status at session start instead of reconnecting immediately:

cached 2h ago · connects on first use · 5 tools

Claude Code loads the server’s tool list from the previous session without establishing a live connection — the server connects on first use, not at session start. This improves cold-start time when many remote servers are configured but not all are needed every session.

Set MCP_DISCOVERY_CACHE=0 to disable caching and force immediate reconnection at session start. Requires Claude Code v2.1.221 or later.

--mcp-config with -p now waits for pending servers to connect before the first turn, but skips the wait for servers with a cached tool list (they connect on first use). The wait behavior itself also requires v2.1.221.

Connector auth fix (v2.1.222)

Before v2.1.222, Claude Code marked connectors as needing authentication even when they were already authorized, and re-authorizing them did not resolve the state. Fixed in v2.1.222 — connectors that are fully authorized no longer appear in the “needs auth” count.

ENABLE_TOOL_SEARCH=true on GCP Agent Platform (v2.1.221)

Before v2.1.221, Claude Code disabled tool search for all models on Google Cloud’s Agent Platform unless ENABLE_TOOL_SEARCH=true was explicitly set. As of v2.1.221, setting ENABLE_TOOL_SEARCH=true reliably forces tool search on even when the model or platform would otherwise suppress it — the beta header is sent regardless. The true value now works as a universal override, not just a GCP-selective one.

Updated ENABLE_TOOL_SEARCH table (updating the true row from the 07-26 entry below):

ValueBehavior (as of v2.1.221)
trueForces all MCP tools deferred; beta header sent even on GCP/proxies and non-first-party hosts. Before v2.1.221, this value did not override the GCP default. May fail on older models that don’t support tool_reference blocks.

Recent additions (2026-07-26 watchlist sweep)

New MCP client features from ai-research/watchlist-snapshots/code-claude-com-docs-en-mcp-2026-07-26.md:

Configure tool search — ENABLE_TOOL_SEARCH env var

Full documentation for controlling tool search behavior. Tool search is enabled by default (all MCP tools deferred and discovered on demand). Disabled by default on Google Cloud’s Agent Platform and when ANTHROPIC_BASE_URL points to a non-first-party host. Set ENABLE_TOOL_SEARCH explicitly to override.

ValueBehavior
(unset)All MCP tools deferred; falls back to upfront load on GCP Agent Platform or non-first-party host
trueAll MCP tools deferred; beta header sent even on GCP/proxies (may fail on older models)
autoThreshold mode: upfront if tools fit within 10% of context window, deferred otherwise
auto:NThreshold mode with custom percentage (0–100); e.g. auto:5 for 5%
falseAll MCP tools loaded upfront, no deferral

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS keeps tool search off and ENABLE_TOOL_SEARCH cannot override it. Requires model supporting tool_reference blocks (Claude Sonnet 4.5, Haiku 4.5, Opus 4.5+).

alwaysLoad per-server and per-tool field

Set alwaysLoad: true in a server’s .mcp.json entry to exempt it from deferral — its tools always load into context at session start regardless of ENABLE_TOOL_SEARCH. Available on all server types (stdio, http, ws). Requires v2.1.121+.

Individual tools can also be marked always-loaded via "anthropic/alwaysLoad": true in the tool’s _meta object. Setting alwaysLoad: true also blocks startup until the server connects (capped at the 5-second connect timeout).

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

anthropic/requiresUserInteraction annotation (v2.1.199)

MCP server authors can mark a tool as requiring explicit user approval on every call. Set _meta["anthropic/requiresUserInteraction"] to the JSON boolean true in the tool’s tools/list response entry. Claude Code shows the permission prompt on every call — even in acceptEdits, auto, and bypassPermissions modes — with no “don’t ask again” option. Allow rules that match the tool don’t skip the prompt. In dontAsk mode, Claude Code denies the call instead.

In non-interactive mode with --permission-prompt-tool, an allow result is converted to a deny with message MCP tool requires user interaction; not supported via --permission-prompt-tool. The Agent SDK canUseTool callback can approve these calls. As of v2.1.214, Claude Code also withholds one-tap Remote Control approval for any permission request the terminal dialog can’t render (safety warnings, always-allow options).

{
  "name": "grant_access",
  "description": "Requests access to a protected resource",
  "_meta": {
    "anthropic/requiresUserInteraction": true
  }
}

OAuth additions: --callback-port, --client-id, oauth.scopes, authServerMetadataUrl

--callback-port <port> and --client-id <id> on claude mcp add and claude mcp add-json:

  • --callback-port fixes the OAuth callback port to match a pre-registered redirect URI (http://localhost:PORT/callback). Works with or without --client-id.
  • --client-id passes a pre-configured OAuth app client ID; --client-secret prompts for the secret with masked input. Store the secret via MCP_CLIENT_SECRET=<secret> env var in CI.
claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

oauth.scopes — pins the OAuth scopes Claude Code requests. Value is a single space-separated string (RFC 6749 §3.3). Takes precedence over authServerMetadataUrl and server-advertised scopes. If the server returns 403 insufficient_scope, Claude Code re-authenticates with the same pinned scopes. offline_access is auto-appended if the server advertises it.

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write"
      }
    }
  }
}

authServerMetadataUrl — overrides default OAuth discovery (RFC 9728 at /.well-known/oauth-protected-resource → RFC 8414 at /.well-known/oauth-authorization-server). Set in the oauth object when standard endpoints error or to route through an internal proxy. URL must use https://. The metadata URL’s scopes_supported overrides upstream advertised scopes.

MCP elicitation response handling

MCP servers can request structured input from users mid-task via elicitation. Claude Code displays an interactive dialog automatically — either form fields defined by the server, or a URL mode for browser-based auth. No user configuration required. To auto-respond without a dialog, use the Elicitation hook (see hooks).

v2.1.214 — list_changed transient error fix

If a list_changed-triggered refresh fails transiently, Claude Code now keeps the server’s previously discovered tools, prompts, and resources until a later refresh succeeds. Before v2.1.214, a transient refresh error replaced the server’s tools with an empty list — breaking tool availability until the next successful reconnection.

v2.1.218 — Startup notice counting fix

The startup notice that appears when configured servers need authentication now counts only servers you can sign in to from Claude Code. Before v2.1.218, it also counted claude.ai connectors not yet connected in claude.ai (those can only be connected from claude.ai settings), inflating the sign-in count.

Recent additions (2026-07-17 — v2.1.212)

  • MCP tool calls auto-background after 2 minutes (CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS, v2.1.212). MCP tool calls that run longer than 2 minutes (120000ms) now automatically move to the background, so the session stays usable during long-running MCP ops (e.g. a slow database query or a file-conversion tool). The threshold is tunable via CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS; set to 0 or a very large value to disable. This makes long-running MCP operations behave more like background Bash commands — the conversation stays responsive while the tool runs to completion. Sourced from ai-research/claude-code-docs-whats-new-w29-2026-07-17.md + ai-research/claude-code-docs-changelog-2026-07-17.md.

Recent additions (2026-07-16 watchlist sweep)

Three changes across v2.1.207/208/211, sourced from ai-research/watchlist-snapshots/code-claude-com-docs-en-mcp-2026-07-16.md:

  • v2.1.207 — Untracked settings.local.json now requires a trust dialog. Approvals in an untracked .claude/settings.local.json still apply, but only after you accept a trust dialog for that folder or a parent directory (unless the folder is your own configuration home). Before v2.1.207, an untracked settings.local.json could approve MCP servers even in a folder you’d never trusted — closing a gap where cloning a repo with a local-settings file could silently auto-approve servers with no trust decision.
  • v2.1.208 — Empty url shows cleanly as “not configured”. A remote server with an empty url now shows as not configured in /mcp, claude mcp list, and the /plugin manager instead of being reported as a configuration issue — lets a plugin ship a placeholder entry for a connector configured later. Before v2.1.208, an empty url prompted to reconnect as if misconfigured.
  • v2.1.211 — Plugin MCP servers reconnect after an idle web session wakes. In web sessions, an MCP call to a plugin server that isn’t connected yet (e.g. right after an idle session wakes) now starts the server on demand and waits for it. Before v2.1.211, plugin servers in a web session reconnected only when the next message started a new turn, so calls right after wake failed until then.

Recent additions (2026-07-12 watchlist sweep)

New MCP client features in Claude Code as of v2.1.202–v2.1.205, sourced from ai-research/watchlist-snapshots/code-claude-com-docs-en-mcp-2026-07-12.md:

  • v2.1.202 — Clearer url-without-type error. Servers configured with a url but no type now report: MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry. Before v2.1.202, Claude Code reported this as command: expected string, received undefined — an opaque internal error.
  • v2.1.203 — roots/list returns all working directories. roots/list now returns the session’s launch directory plus every additional working directory you’ve added with --add-dir, /add-dir, or additionalDirectories. Claude Code also sends notifications/roots/list_changed when that set changes. Before v2.1.203, roots/list returned only the launch directory and no change notifications were sent.
  • v2.1.203 — stdio servers now subject to idle timeout. The idle timeout now applies to stdio servers (30-minute window, previously exempt). HTTP/SSE/WebSocket servers keep the 5-minute window. IDE servers and SDK in-process servers remain exempt.
  • v2.1.203 — Per-server timeout floors the idle timeout. A per-server timeout ≥1000ms also acts as a minimum on the idle timeout for that server — Claude Code will never kill it for idleness sooner than the configured timeout.
  • v2.1.205 — Claude Browser added to reserved server names. Names workspace, claude-in-chrome, computer-use, Claude Preview, and now Claude Browser are reserved for Claude Code’s built-in servers. A user-configured server with a reserved name is skipped at load time.
  • v2.1.205 — Connection errors passed to Claude via ToolSearch. When a configured server fails to connect, Claude Code now reports which server failed and its error in ToolSearch results, so Claude can surface the failure in its response. Before v2.1.205, Claude responded as if the failed server’s tools were never configured. Requires Tool Search (default on); not available on Bedrock/Vertex/Foundry, custom ANTHROPIC_BASE_URL, ENABLE_TOOL_SEARCH=false, or Haiku.

Recent additions (2026-07-05 watchlist sweep)

New MCP client features in Claude Code as of v2.1.196, sourced from ai-research/watchlist-snapshots/code-claude-com-docs-en-mcp-2026-07-05.md:

  • WebSocket transport (type: "ws") — A third transport option alongside stdio and HTTP. Holds a persistent bidirectional connection; suited for remote MCP servers that push events to Claude unprompted. Use HTTP instead for servers that only respond to requests (HTTP supports OAuth and claude mcp add --transport; WebSocket supports neither). Configure via claude mcp add-json or directly in .mcp.json. Authentication is header-only — pass a static token in headers or generate one with headersHelper.
  • v2.1.196 — Workspace trust gate on .mcp.json approvals. claude mcp list and claude mcp get now read .mcp.json approvals only from settings that aren’t checked into the repository, until you trust the workspace by running claude interactively and accepting the trust dialog. A cloned repository can no longer approve its own servers: enableAllProjectMcpServers or enabledMcpjsonServers committed to .claude/settings.json is ignored in an untrusted folder, and the server shows ⏸ Pending approval instead of connecting. Approvals from user ~/.claude/settings.json, managed settings, --settings, and .claude/settings.local.json (untracked) still apply. A disabledMcpjsonServers entry still rejects the server.
  • workspace server name reserved. A server named workspace in any configuration is skipped at load time with a warning asking you to rename it.
  • /mcp panel tool count. The /mcp panel now shows the tool count next to each connected server and flags servers that advertise the tools capability but expose no tools.
  • streamable-http as alias for http. The MCP spec uses streamable-http as the transport name, so configurations copied from server documentation can use either streamable-http or http in the type: field — both work identically.

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