model-context-protocol

Model Context Protocol (MCP) — the protocol claude-code uses to plug external systems (GitHub, Sentry, databases, …) into the agent. Each external system runs as an “MCP server” exposing a set of tools that the model can call (2026-04-27-claude-code-architecture-governance-engineering).

The hidden context cost

MCP is the largest fixed context cost in a typical claude-code session:

• A representative server defines 20–30 tools.
• Each tool definition averages ~200 tokens (name + description + JSON schema).
• → One server: 4–6K tokens, resident for every request.
• → Five connected servers: ~25K tokens / 12.5% of the 200K budget gone before the user types (context-engineering).

This persists across the whole session because tool definitions sit in the cached prefix — moving them out would break cache.

Mitigations Claude Code applies

• defer_loading: true — ship a lightweight stub (just the tool name) for low-frequency tools; full schema loads only after the model picks the tool via ToolSearch. Keeps the cache prefix stable while shrinking resident size (prompt-caching).
• /mcp — slash command listing connected servers, their tool counts and token cost; lets the user disconnect idle servers.

Operating heuristics

• Connecting an MCP server has a cost paid every request, not just when used. Audit periodically.
• If an MCP server’s tools are only used in one workflow, consider wrapping that workflow as a Skill that the user invokes explicitly, instead of leaving the server permanently connected.
• Distinct from a claude-code plugin, which is a packaging/distribution unit that may bundle Skills, Hooks, and MCP servers together. MCP is the runtime integration; plugin is the delivery vehicle.

Common confusion

tw93 explicitly disambiguates (2026-04-27-claude-code-architecture-governance-engineering):

• Built-in Tools → things like Read / Edit / Bash / Grep, shipped with Claude Code.
• MCP → protocol for connecting external systems as additional tools.
• Plugin → packaging layer for distributing Skills / Hooks / MCP-server bundles together.

A common anti-pattern is treating “plugin” as a runtime primitive rather than a distribution wrapper.

Open question — definition-size figures vary

2026-04-27-agent-principles-architecture-engineering cites a different ballpark for the same shape: “5 MCP servers ≈ 55K tokens of tool definitions.” The prior figure here is ~25K. Both come from tw93. Likely either different MCP-server samples or different counting (full schema vs. compressed names). Not yet resolved — would benefit from a real /mcp reading on a representative install.