Learning objectives

By the end of this chapter, you will be able to:

1. Explain why MCP exists — the N×M integration problem — and the shape it imposes on AI apps (hosts, clients, servers; the one-client-per-server constraint; tools, resources, and prompts as the three primitives).
2. Add an MCP server to Claude Code with `claude mcp add`, place it at the right scope (`local` / `project` / `user`), and audit what's connected with the `/mcp` slash command.
3. Diagnose MCP-driven context bloat with `/context`, claw it back with `--mcp-config` + `--strict-mcp-config` and per-session disable, and explain *why* preloaded tool descriptions are the failure mode.
4. Name MCP's structural limitations — context pollution, ping-pong execution, JSON-tool-call vs. code, schemas that describe shape but not intent — and explain how *code execution against MCP* (Anthropic's pattern, parallel to Cloudflare CodeMode) addresses them.
5. Install, inspect, and run a Claude Code plugin from the official marketplace, and explain what `plugin.json` and `marketplace.json` bundle together (skills, sub-agents, MCP servers, hooks).

Before we start — MCP, hosts/clients/servers, and plugins in plain language

Skim this if you already know what MCP is, what a host / client / server are, and what a Claude Code plugin bundles. If any of those four ideas is fuzzy, read this first — every section below assumes them.

MCP — Model Context Protocol — is a small standard for how an AI app talks to outside tools. Without it, every AI app reinvents the wiring to Slack, to Gmail, to your database, to GitHub. With it, you wire each tool once, behind a common shape, and any AI app that speaks the protocol can reach it. Anthropic introduced MCP in November 2024; it was donated to the Linux Foundation in December 2025 and now sits with the wider open-source ecosystem.

Three roles to keep straight:

• A host is the AI app the human uses — Claude Code, Claude Desktop, Cursor, an agent inside your own product. Hosts are where the conversation lives.
• An MCP server is the wrapper around an outside capability — a service that exposes tools (e.g. "get the weather"), resources (e.g. a PDF), or prompts (e.g. a templated request) using the MCP shape. The server doesn't talk to the LLM directly; it talks to the host through the protocol.
• An MCP client is the connector inside the host that speaks the protocol to one server. The connection is one client per server — if a host needs to talk to three servers, it spins up three clients.

A plugin is Claude Code's recently-introduced way to bundle MCP servers together with skills, sub-agents, slash commands, and hooks into a single installable package. A marketplace is a tiny JSON file that lists plugins so people can find them with /plugin. The official Claude Code marketplace lives in the public anthropics/claude-code repository.

Why this chapter matters

Chapter 1 was the theory — context engineering and the four strategies. Chapter 2 was the startup pass — CLAUDE.md, permissions, MCP at first sight, plan mode. Chapter 3 was the daily operating surface — commands, hooks, memory, rewind, Skills. Chapter 4 is where Claude Code learns to talk to the rest of your stack. Without MCP, Claude Code can read your files and run your shell — that's the toolbox it ships with. With MCP, the same Claude Code can pull live documentation from Context7, search the web with Tavily, drive a browser with Playwright, query your team's GitHub, watch your CI, read your Linear board. Plugins are the next step up: bundles other people built, packaged so you can install them by name and inspect them before you do.

The trick — and most of this chapter is about this trick — is that MCP servers don't come for free. Every server you add preloads its tool descriptions into the model's context before you even type a prompt. Get this wrong and you start every session with a polluted context window, an agent that can't decide which of forty tools to call, and a bill that goes up because every round trip carries that polluted history. Get it right and MCP is one of the highest-leverage moves in Claude Code.

Lesson

1. Why MCP — the integration problem and the portability tax

Picture an AI agent that should be able to send Slack messages, read and send Gmail, and query your team's database. The naive way to build this is to write three integrations directly into the agent: one Slack wrapper, one Gmail wrapper, one database wrapper. That works — until someone wants the same agent inside Claude Code instead of Cursor. The functionality is conceptually the same, but the wrapper code lives inside Cursor's runtime and isn't reachable from Claude Code's. So you rewrite all three integrations. Then someone wants them in GitHub Copilot. Then in a fourth tool. At N agent hosts and M integrations, you're on the hook for N × M wrappers, all kept in sync.

This is the integration problem MCP solves. The book quotes Andrew Koenig: "We can solve any problem by introducing an extra level of indirection." The extra level is an MCP server — one wrapper, one implementation, exposed through a common protocol. Any host that speaks MCP — Claude Code, Cursor, Claude Desktop, ChatGPT, Gemini CLI, and a long tail of others — can connect to that server. The integration cost drops from N × M to N + M. You write your Slack server once. Every host gets it.

The flip side of the same coin is the network effect. As more hosts speak MCP, every new MCP server reaches more places for free. As more MCP servers exist, every new host gets a richer toolbox the moment it adopts the protocol. By the time MCP was donated to the Linux Foundation in late 2025, Anthropic's count was past ten thousand public MCP servers — Claude Code, ChatGPT, Cursor, Gemini, Copilot and others all read from the same well.

Analogy — the universal travel adapter Before the universal adapter, the drawer in your bag held one plug per country times one plug per device — a thicket. After: one adapter brick in the middle, and every device plugs into it on one side, every wall plugs into it on the other. The adapter doesn't make your devices smarter or your sockets richer. It changes who has to do the wiring, and how many times.

2. Core architecture — hosts, clients, servers

MCP has a small surface. Three roles, three primitives, two transports. Everything in this chapter sits on top of that.

The three roles (you met them in the preface; here they are with more detail):

• A host is the AI application — the thing the human is talking to. Examples: Claude Code, Claude Desktop, Cursor, ChatGPT desktop, a custom agent inside your own product. The model runs here. Permission prompts surface here. The conversation history lives here.
• An MCP server is the wrapper around something the host wants access to. The server speaks MCP on the outside and whatever it likes — the Gmail API, your Postgres connection, a Playwright runtime — on the inside. The official MCP organisation publishes a reference set of servers; thousands more live elsewhere on GitHub or as hosted services. The official MCP registry is the searchable catalogue.
• An MCP client is the connector inside the host that speaks MCP to one server. The constraint to memorise: one client per server. If a host needs to talk to three MCP servers, it instantiates three clients, each holding a private connection to its server. There's no client that "fans out" to several servers.

The three primitives an MCP server can expose:

For Claude Code, tools are the workhorse. The book's examples (getForecast, getAlerts, Context7's resolve-library-id and get-library-docs) are all tools. Resources and prompts exist and are useful, but most of the value you'll get out of MCP day-to-day is tool-shaped.

The two transports an MCP server can use to talk to its client:

• stdio — the server is a subprocess of the host. The host writes JSON-RPC messages to the subprocess's stdin and reads responses from stdout. Best for local servers that run only on your machine — fast, no network surface, but you have to have the runtime (Node, Python, a compiled binary) installed locally.
• Streamable HTTP — the server runs as an HTTP endpoint. The host sends POST requests with JSON-RPC; the server can stream responses with Server-Sent Events. Best for remote servers (hosted by a third party) and for servers you want multiple hosts on different machines to share. This is what Context7's hosted endpoint at https://mcp.context7.com/mcp uses. (Older docs sometimes call this just "HTTP" or "SSE" — the current spec name is Streamable HTTP; the protocol page is at /specification/.../basic/transports.)

MCP today — a quick governance note. Anthropic introduced MCP in November 2024. In December 2025 it was donated to the Linux Foundation under the umbrella of the new Agentic AI Foundation. The spec, the reference implementations, and the open registry all sit there now; Anthropic is one steward among many. The book frames MCP as Anthropic-owned because the book pre-dates the donation. Read the protocol pages on modelcontextprotocol.io rather than the book if you want today's authoritative shape.

Analogy — a restaurant pass A host is the restaurant — the place the diner orders from. A kitchen station (grill, pastry, line) is an MCP server — each station has its own tools and its own specialty. A waiter is an MCP client; each waiter works one station at a time. If the chef wants the order to touch the grill, pastry, and the line, three waiters are needed. The diner doesn't see any of this — they see plates arrive. The protocol is the standard slips the waiters and stations use so any kitchen can rotate any waiter into any station.

3. MCP in action — adding Context7 to Claude Code

The single most useful first MCP server to install is Context7 — a hosted server that serves live documentation for ~30,000+ libraries. Most coding agents lose a percentage point of accuracy every month as frameworks evolve past their training cutoff. Context7 closes the gap by injecting the current docs into the context on demand.

Here's the end-to-end install in Claude Code.

Step 1 — Confirm nothing's connected yet. From the Claude Code prompt:

/mcp

If the project has no .mcp.json and your user file has no MCP servers, the panel lists nothing.

Step 2 — Add Context7 at project scope. From your shell (not from inside Claude Code):

claude mcp add --scope project --transport http context7 https://mcp.context7.com/mcp

Breaking that down:

• claude mcp add — the CLI subcommand that registers a new server.
• --scope project — write the entry to the project's shared .mcp.json. Without --scope, Claude Code defaults to local scope — the entry goes into ~/.claude.json under the current project's path, private to you, not committed. The next section unpacks the three scopes; for this walkthrough we want the team to see the server, so we pass --scope project explicitly.
• --transport http — the transport. Use --transport stdio (the default) for local servers, --transport http for remote ones.
• context7 — the name you'll see in /mcp and the key in the JSON.
• https://mcp.context7.com/mcp — the server URL.

Other flags worth knowing: --header "K: V" to add an HTTP header (often used for an API token), and --env K=V for stdio servers that read environment variables. Run claude mcp add --help for the current full list; the CLI is the canonical source.

Step 3 — Inspect what got written. With --scope project, the command creates or updates .mcp.json in your project root:

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

This file is meant to be committed to the repo — anyone else who runs Claude Code in this directory picks up the same MCP setup.

Step 4 — Restart Claude Code so it sees the new file. Exit the session and claude again from the same directory. On startup, Claude Code detects .mcp.json and asks you to approve the connection. Approving once writes the approval into .claude/settings.local.json (per-user, gitignored). You won't be asked again on this machine for this server.

Step 5 — Confirm it's wired up. Inside Claude Code:

/mcp

Now you see context7 listed as connected. Drilling in shows its two tools:

• resolve-library-id — given a library name, return Context7's internal id.
• get-library-docs — given the id, return the current docs.

These tool names and descriptions are now part of every prompt's context — more on this in §5.

Step 6 — Use it. Ask:

What is the latest version of LangGraph?

Claude Code asks for permission to call the Context7 tool on first use, you approve, and Claude resolves the library id and pulls the current docs. The answer reflects today's LangGraph version — not whatever was in the model's training data.

Step 7 — Make it stick. If you want Claude Code to prefer Context7 whenever you ask about LangGraph (or any other library), drop a line into CLAUDE.md in the project root:

When discussing LangGraph, prefer the Context7 MCP for current docs.

Now, in any future session, Claude Code reads that rule from project memory and reaches for Context7 without being asked.

stdio vs HTTP at a glance:

Analogy — plugging in a USB device The first time you plug a USB device into a new OS, the system pops a permission dialog. Approve it once, the device shows up in the device list, and you can use it. Restart, plug it in again, no second prompt — the approval persisted. claude mcp add is the plug-in. The first invocation is the permission dialog. /mcp is the device list. .mcp.json is the OS's record that this device is now allowed in this room.

4. MCP scope hierarchy — local, project, user

MCP servers live at one of three scopes: local (the default), project, and user. Picking the wrong one is the most common configuration mistake — secrets get committed, personal preferences leak into team setups, and --strict-mcp-config doesn't behave the way you expect.

A quick aside about naming: the book uses the labels project / user / session — that was the surface as of the book's writing. Current Claude Code docs use local / project / user. Local is what the book intuits as "session-ish" — it's specific to you in this project — but it actually persists across sessions; it just lives in your personal file rather than the team file. There is no "session" scope in the current model. Truly session-only behaviour (load this config for this one process only) is achieved with the --mcp-config / --strict-mcp-config CLI flags, which are not a scope but an override on top of the three-scope hierarchy. We use the canonical names below.

~/.claude/settings.json is not used for MCP — it's a common mistake. MCP entries live in ~/.claude.json (note: no /settings.json).

A pragmatic decision tree:

• Does the team need it in this repo? → project scope. Add with --scope project; the entry lands in .mcp.json and gets committed.
• Do you need it across every project on your machine? → user scope. Add with --scope user; the entry lands in ~/.claude.json at the top level.
• Are you trying it out in just this one project, with secrets you'd rather not commit? → local scope. Add with no --scope flag (or --scope local explicitly); the entry lands in ~/.claude.json under the current project's path.

The override flags — temporary by-pass of the hierarchy. Two CLI flags govern what Claude Code loads at startup:

• claude --mcp-config <path> adds the servers in <path> on top of whatever the three scopes already provide. The hierarchy still applies.
• claude --mcp-config <path> --strict-mcp-config loads only the servers in <path> and ignores the three scopes entirely. This is the override you reach for when you want a known-clean, minimum-MCP session — for example a research session that needs only Tavily and nothing else.

You can also pass --mcp-config multiple times (or with space-separated paths) to layer several scoped files.

API keys and secrets — where to put them. Project .mcp.json is committed to the repo. Do not put live API keys in it. Three safe patterns:

1. Use ${API_KEY} placeholders in .mcp.json and rely on Claude Code's environment-variable expansion. The variable lives in your shell or in .env, not in the repo.
2. Put the whole server entry in local or user scope instead — both live outside the repo.
3. For one-off processes, pass the secret as --env API_KEY=... when starting Claude Code, and load via --mcp-config.

Analogy — three drawers in your toolbox The project drawer is the shared one bolted to the workshop wall — anyone on the team can open it and grab what's inside. The user drawer is your personal toolbelt — it goes with you between workshops. The local drawer is the one in your locker at this workshop — yours alone, but only when you're here; back at home base you don't see it. The override flags (--mcp-config / --strict-mcp-config) aren't a drawer at all — they're a temporary lanyard you put on for one shift that says only the tools I named today; ignore the drawers entirely.

5. Context engineering for MCP

Here is the rule that makes or breaks every MCP setup. An MCP server's tool descriptions are loaded into the model's context at the start of every session. Not on demand, not when the tool is called — at startup, before you've typed a single character. The host needs to know what tools exist in order to decide whether to call any of them. The book's example: four MCP servers (a verbose math server, Context7, Tavily, Playwright), each with several tools, each tool carrying a long description so the host can pick wisely. The result, from running /context immediately after start:

• About 2,000 tokens for Claude Code's own system prompt
• About 12,000 tokens for Claude Code's built-in tools
• About ~20% of the context window for MCP tool descriptions
• Zero tokens of user message — you haven't said anything yet

That's nearly half the context window consumed before the conversation begins. Every prompt afterwards carries that same overhead because tool descriptions persist for the whole session.

Three ways to fix it

Fix 1 — Scope the MCP config to the task. Don't put every MCP server you might ever use in the project .mcp.json. The book's example: keep a project-level .mcp.json.tavily that contains only Tavily (the research task at hand needs web search and nothing else). Then start Claude Code with:

claude --mcp-config .mcp.json.tavily

But that only adds Tavily on top of whatever your user-scope file already loads. To load only Tavily and nothing else, add --strict-mcp-config:

claude --mcp-config .mcp.json.tavily --strict-mcp-config

The strict flag tells Claude Code to ignore the inherited scopes — user, project — and load only the file you named. The book's measurement: MCP-related context drops from ~20% to ~2.4%, freeing roughly 17–18% of the context window for actual work. Same project, same task — only the startup config changed.

Fix 2 — Disable servers per-session, no file edits. Once Claude Code is running, /mcp opens an interactive panel where you can disable specific connected servers for the rest of the session. The book's measurement when disabling the verbose math server and Playwright (keeping Context7 and Tavily): MCP-related context lands at ~3.2%. Less surgical than --strict-mcp-config but doesn't require restarting.

Fix 3 — Don't expose tools you don't use. If you're the author of an MCP server, every tool you ship is paid for in the context window of every host that loads your server. Anthropic's writing-effective-tools-for-agents post makes this argument at length: ship a few high-leverage tools with crisp descriptions, not a kitchen sink. The same logic applies when you pick servers — if a server exposes 40 tools and you'll use 3, prefer a smaller specialised server if one exists.

Tying it back to Chapter 1

This is the Select strategy from Chapter 1, applied to MCP. The Claude Code context window is finite. MCP tool descriptions are not exempt from that finite budget. Bringing them down isn't about saving money — though it does — it's about giving the agent room to think about your actual task. An agent that sees three relevant tools makes better choices than an agent that sees forty.

Analogy — a desk piled with manuals you'll never open today Imagine sitting down to write one chapter of a book and finding the desk already covered with manuals for the printer, the espresso machine, the air-con unit, the photocopier, and every other appliance in the building. They're useful — sometimes. But not today, not for this chapter. You have to clear the desk before you can think. Scoping MCP is clearing the desk. --strict-mcp-config is the trash can you put the rest of the manuals into for the day.

6. MCP's current limitations

MCP is the right shape for the integration problem. It's also a young protocol, and several drawbacks fall out of the way it's designed. Knowing them in advance keeps you from blaming the agent when the protocol is the culprit.

Limitation 1 — Context pollution from preloaded tool definitions. You met this in §5. Tool descriptions sit in the system prompt for the whole session. With many servers, definitions alone can consume tens of thousands of tokens before any prompt is written; in extreme configurations (the book mentions setups with 58 tools across GitHub, Slack, and internal MCPs), it can pass 55,000 tokens. The needle-in-a-haystack failure mode kicks in: the model has to search through descriptions of database utilities and PDF readers to find the one tool relevant to a frontend edit. Hallucinations, wrong tool picks, and instruction-following failures rise as the pollution rises.

Limitation 2 — Ping-pong execution. Tool calling is structurally a round trip. The model emits a special "I want to call tool X with args Y" token sequence. The host parses it. The host executes the tool. The result is appended to the conversation. The whole updated history is sent back to the model for the next decision. Each step is one full LLM inference. Five tool calls = five inferences and a conversation history that grew on every hop. Latency and cost both compound. Even when intermediate tool outputs are no longer needed, current MCP implementations retain them in context.

Limitation 3 — JSON tool-call format isn't the model's native tongue. Modern LLMs are trained primarily on natural-language text and code. The special tokens that represent tool calls are a synthetic construct introduced during fine-tuning. Vendors have invested heavily in making tool calls reliable — and the major models are now quite good at it — but the format is structurally not what the model is best at. Asking a model to compose nuanced behaviour through nested JSON schemas is asking it to operate slightly outside its strongest distribution.

Limitation 4 — Schemas describe shape, not intent. A JSON schema can tell the model getForecast takes a latitude and a longitude and returns a temperature. It can't tell the model when to use getForecast versus when to use the search tool. It can't tell the model that calling deleteEmail is one of the most dangerous things in the toolkit. Behavioural constraints — when to use this, when not to, what to be careful about — have to live in the description string and the surrounding prompt. The protocol gives you the structural part for free; the behavioural part is on you.

Analogy — a walkie-talkie game of telephone Suppose you want a contractor to fetch six tools from the truck. Over a walkie-talkie, you ask for tool one. They walk to the truck, find it, walk back, hand it to you, and the line buzzes. You ask for tool two. They walk back to the truck. Six trips, six handoffs, and every transmission carries the whole conversation so far. A faster shape: write a list of six tools, hand it over once, and let the contractor make one trip with the list. That's the limitation MCP imposes and the limitation the next section addresses.

7. Code execution against MCP — the direction of travel

In November 2025, Anthropic published a post titled "Code execution with MCP: Building more efficient agents." The argument is the one the walkie-talkie analogy points at: if the model can write code that calls MCP tools, instead of emitting one tool call at a time, you save both the round trips and the context pollution. Anthropic reports a worked case going from 150,000 → 2,000 tokens — a 98.7% reduction — driven by three combined effects: (1) on-demand tool-definition loading (the agent reads only the tool defs it actually needs from the filesystem, instead of the host preloading all of them at session start), (2) code execution against a typed API so the model writes one program that does the whole task, and (3) keeping intermediate tool outputs out of the prompt — only the final result re-enters the model's context.

Cloudflare published the same idea earlier, in September 2025, under the name Code Mode. Cloudflare's framing: take the MCP schema, generate a TypeScript API from it, give the model a sandbox that runs TypeScript, and let the model write a single program that does the whole task. A February 2026 follow-up post by Cloudflare describes compressing Cloudflare's full 2,500+ endpoint API down to ~1,000 context tokens through this approach. The two pieces of work — Anthropic's and Cloudflare's — converge on the same shape from slightly different starting points.

The shape, in three bullets

• Traditional MCP: the agent loop is "model → tool call → result → model → next tool call → result → ..." for N tools. Each step is one LLM inference. Intermediate results accumulate in the prompt.
• Code-against-MCP: the model is given one tool — execute this block of code — and a typed API representation of every MCP server it can reach. It writes a small program that calls those APIs in sequence, runs it once in a sandbox, and returns only the final result. One inference, one execution, one result back into the prompt.
• The argument for the change is structural, not just performance: LLMs have seen vast amounts of real-world code in training, and only a synthetic sliver of tool-call formats. Code is closer to the model's native distribution.

One important caveat

This is the direction of travel, not yet the default behaviour. Claude Code (as of writing) still runs MCP the traditional way — tool-call by tool-call. The patterns described in Anthropic's "code execution with MCP" post and in Cloudflare's CodeMode posts are how agent builders using the Anthropic API or Cloudflare's Agents SDK can change the underlying loop. Watch the docs for when (or if) the pattern lands in Claude Code itself. The important takeaway today: when you find yourself with too many MCP tools to fit in context, the protocol is not against you — there's a known structural fix on the horizon.

Analogy — from dictation to writing code Imagine working with an assistant by walkie-talkie. "Look up X. ... OK, now look up Y. ... OK, now combine them like so. ..." Slow, verbose, error-prone, and every transmission carries the whole conversation so far. Now imagine handing the assistant a one-page script — look up X, look up Y, combine like so, send me the result. The assistant goes off, does the work, and reports back once. Same task, fewer transmissions, and the script can use loops and conditionals the walkie-talkie can't. That's the difference between tool-call-by-tool-call and code-against-MCP.

8. Claude Code plugins — bundling MCP + skills + sub-agents + hooks

By Chapter 4, you've built — across the book — Skills (slash commands), sub-agents, hooks, and MCP server connections. Each of those is a separate file in .claude/. Sharing them with a teammate used to mean walking them through copying each file by hand: "drop this in your .claude/commands/; add this server to your .mcp.json; here's the hook config to paste into settings.json." Tedious, fragile, and impossible to update once distributed.

A plugin is Claude Code's answer. A plugin is a directory with:

• A .claude-plugin/plugin.json file describing the package (name, version, description, author).
• Optional sub-directories: skills/, commands/, agents/, hooks/, plus an .mcp.json for MCP servers the plugin needs.

Install a plugin and Claude Code wires up every one of those components for you. Uninstall and they're removed together. Update and you get the new version with one command.

A marketplace is one level above a plugin. A marketplace is a JSON file (marketplace.json) that lists multiple plugins with their source paths. You add a marketplace once, browse the plugins it advertises, and install the ones you want.

Two Anthropic-published marketplaces are worth knowing apart:

• The official Anthropic marketplace — claude-plugins-official. Auto-loaded when you start Claude Code; you don't add it manually. This is where production-quality, Anthropic-maintained plugins live.
• The demo / examples marketplace — claude-code-plugins, in the public anthropics/claude-code repo at .claude-plugin/marketplace.json. Not auto-loaded; you add it with /plugin → Add marketplace → the repo URL. As of writing it ships demo plugins including agent-sdk-dev, commit-commands, code-review, feature-dev, pr-review-toolkit, plugin-dev, security-guidance, frontend-design, and several more — they're worked examples meant to be read as well as installed. Check the live marketplace.json for the current list.

The end-to-end flow

Step 1 — Add a marketplace. Inside Claude Code:

/plugin

Choose Browse and install plugins → Add marketplace. Paste a GitHub repo URL (e.g. https://github.com/anthropics/claude-code) or a direct link to a marketplace.json. Claude Code detects the marketplace file and loads the plugin catalogue.

Step 2 — Inspect a plugin before installing. This is the single most important step and the one most often skipped. A plugin can ship arbitrary code, arbitrary MCP servers, and arbitrary hooks. Open the plugin's source on GitHub before installing. Look at:

• plugin.json — what does it claim to install?
• hooks/ — what runs automatically?
• .mcp.json — what external services connect on session start?
• agents/ and commands/ — what prompts are saved with what frontmatter (and what allowed-tools grants)?

The same security mindset as third-party MCP servers from Chapter 2: treat plugins as third-party code. Trust the author, or read the source.

Step 3 — Install. From the /plugin interface, pick Install on the plugin you want. Claude Code writes its contents into your .claude/ directory (the exact layout is in the plugins reference). After install, the plugin's commands, skills, agents, hooks, and MCP servers are live.

Step 4 — Verify. Run /plugin list to see installed plugins; /mcp to confirm any MCP servers the plugin added are connected; /skills to see any skills it shipped; /hooks to see any hooks it registered. If something looks off, that's the moment to find out.

Step 5 — The lifecycle commands. Plugins are backed by their source repos. The full set:

(The book describes uninstall as broken in late-2025 builds; current docs ship uninstall as a documented, reliable command — don't carry that historical caveat forward.)

Step 6 — Reload without restarting. If you've edited a plugin's files (you're developing one, or patching one), /reload-plugins picks up the changes in the running session. Restart is only needed if .claude/ itself didn't exist when the session started.

Slash-command namespacing — the rule worth memorising

When a plugin ships a slash command, it doesn't land as a bare /<command>. Plugin-provided commands are always namespaced as /<plugin-name>:<command-name> to avoid collisions when multiple plugins offer commands with the same name. The plugin's name field in plugin.json is the namespace prefix. So a plugin called my-first-plugin that ships a hello command exposes it as /my-first-plugin:hello. The canonical docs phrase it as: "Plugin skills are always namespaced (like /my-first-plugin:hello) to prevent conflicts when multiple plugins have skills with the same name."

This is the single most common surprise when installing a plugin and not being able to find its commands in the / menu — you're typing the bare name and the autocomplete is hiding it behind the namespace.

One worked example — the feature-dev plugin

The Anthropic demo marketplace ships a feature-dev plugin that bundles three sub-agents (code reviewer, code explorer, code architect) and one or more slash commands exposed under the /feature-dev: namespace. When you install it, hit / and look for the feature-dev: prefix to see what it offers — the exact command names depend on what the plugin manifest declares at the version you pulled. The classic flow the book walks through asks what you want to build, inspects git state, stashes uncommitted work if needed before switching branches, walks through a target branch, returns to your working branch, restores your stash, and proposes a change. It's a worked example of how a plugin can chain skills + sub-agents + git operations into something that looks like a single mini-app.

The argument for the plugin shape is the same as the argument for any package manager: rebuilding the same workflow three times is wasted work; sharing it once means everyone on the team gets the upgrade when the author ships one. Plugins are early — the ecosystem is small in mid-2026 — but the direction is clear.

Analogy — an app store with a code-review pane A plugin marketplace is the app store. Plugins are the apps. The catalogue is browsable, install is one command, update is one command, uninstall is one command. The difference from a phone app store: there's no sandbox between you and the app's code. The plugin runs as your user, can read your files, can call out to MCP servers it shipped with. The "code-review pane" is on you — every store should have one, and this one effectively does, in the form of the public repo where every plugin's source is visible. Look before you install.

The whole chapter in one image — the universal cable

Analogy — pedagogical summary, drawing on all eight sections

Picture your machine as a workbench, and Claude Code as the apprentice working on it. Without MCP, every outside tool — your team's database, the documentation server you actually trust, the issue tracker, the web search you rely on — needs a custom cable wired straight from the apprentice's hands to the appliance. Each cable is a wrapper you wrote, and each cable only fits one apprentice. When the next apprentice arrives, you wire all of those cables again.

MCP is a standard plug. One side fits every modern apprentice. The other side fits anything you wire to it. Once you've wired the database to the MCP plug, every apprentice can use the database without a single custom cable.

The plug has three shapes you have to keep straight: the host is the apprentice, the server is the appliance behind the plug, and the client is the single-purpose cable inside the apprentice. The protocol speaks three primitives — tools to do things, resources to read things, prompts to ask templated things — over two transports (stdio for local appliances, Streamable HTTP for remote ones).

You decide which appliances are plugged in where. The shared appliances for the team — your project's specific MCP servers — live on the wall by the workbench, in .mcp.json. Your personal appliances — your GitHub PAT, your Linear, your Tavily search — live on your private workbench at home, in ~/.claude.json. Tonight's experimental appliance lives on a temporary extension cord, plugged in only for this session via --mcp-config. And when you really want a clean room with only the appliances you named tonight, you yank the wall-mounted cords by adding --strict-mcp-config.

The cost of plugging in too many appliances is that the apprentice's worktop fills with manuals before the day starts. Every appliance brings its instruction sheet, and the apprentice has to read all of them every morning. The fix is either to keep fewer manuals on the worktop (scope your MCP config) or — eventually — to teach the apprentice to handle a stack of appliances by writing a single short program instead of reading and acting on each manual one at a time. That's the code-against-MCP shift.

And finally: when a setup is good — a particular combination of appliances, an apprentice's notebook entries, a couple of jigs and safety interlocks — you can box it up as a plugin and hand it to a teammate. They install it once and the whole workbench mirrors yours. Plugins are how a personal setup becomes a team setup. Marketplaces are how a team setup becomes an industry setup.

That's the chapter. The protocol is small. The discipline is in what you plug in, where, and how much of it you let the apprentice carry in the head at once.

Activity — Audit your current MCP setup

Spend ten minutes on a project you've been using Claude Code in.

1. Inside Claude Code, run /mcp. Write down every server that comes up and which scope each lives in (local / project / user). If you can't tell, find the config file by hand: .mcp.json in the project root is project; the top-level mcpServers block in ~/.claude.json is user; an entry under the current project's path inside ~/.claude.json is local. Anything that disappears when you exit Claude Code came from a --mcp-config flag.
2. Run /context. Note the rough percentage of the window taken by MCP tool descriptions specifically (the breakdown often calls them out as their own block).
3. For each server in your list, answer:

• Do I actually use this in this project, this week? If no — strong candidate to move to user scope, demote to a scoped file, or remove.
• Does anyone else on the team need this server? If yes — project scope. If no — user scope.
• Does any of this contain secrets? If yes — pull the secret out of the committed file; use env-var expansion or move to user scope.

1. Sketch a "clean run" startup command — what would claude --mcp-config <file> --strict-mcp-config look like if your goal was to minimise MCP context for the next 30 minutes of work? Write the file path, what would be in it, and the command line.

Capture three concrete moves (e.g. "moved Tavily from project to user scope," "created .mcp.json.research for read-only research sessions") in a note. Reuse them when you bootstrap your next project.

Stretch — design a project-shaped plugin

Pick a workflow you do at least once a week — your team's deploy ritual, your PR-review ritual, your incident-triage ritual. Sketch what would go into a plugin for it:

• Which MCP servers does it need?
• Which sub-agents would specialise in parts of it?
• Which hooks would tie it together?
• Which slash command would the user type to kick it off?

You don't have to build it — sketching the layout teaches you which problem a plugin is actually shaped to solve.

Practical exercise — Drive MCP scope, context, and plugins on a sandbox project

~30–40 minutes. Hands-on. Bring a terminal, a text editor, and Claude Code installed. Optional: a free Tavily API key from https://tavily.com — the exercise works without one if you skip the user-scope step. You'll work in a throwaway sandbox outside the training repo. Nothing in this exercise touches the training repo or any project you care about.

Setup (3 min)

mkdir -p ~/cct-ch4-exercise
cd ~/cct-ch4-exercise
git init -q
echo "# Sandbox" > README.md
git add . && git commit -q -m "init"
claude

You should land at the Claude Code prompt inside ~/cct-ch4-exercise. Leave it open — every step below runs there or edits a file in your editor.

Step 1 — Confirm a clean baseline (3 min)

Goal: see what MCP looks like in a fresh sandbox, and capture a context baseline.

1.1 Inside Claude Code:

/mcp

Expected: if you've never added any user-scope MCP servers, the panel says no servers are connected. (If you have user-scope servers from previous projects, note them — they'll show up here regardless of which directory you're in.)

1.2 In Claude Code:

/context

Expected: the panel shows roughly the breakdown of your current context — system prompt, built-in tools, and however much MCP weighs from your user-scope setup. Note the MCP percentage. Write it down. You'll compare against it in Step 4.

Step 2 — Add Context7 at project scope (5 min)

Goal: wire up a real hosted MCP server and watch what gets written to disk.

2.1 Exit Claude Code (/exit). From the shell, in ~/cct-ch4-exercise:

claude mcp add --scope project --transport http context7 https://mcp.context7.com/mcp

Note the --scope project. Without it, Claude Code would default to local scope and write the entry into ~/.claude.json under this project's path — private to you, not committed. We want a shared .mcp.json for this walkthrough.

Expected: the command reports success. Cat the resulting .mcp.json:

cat .mcp.json

You should see Context7 listed under mcpServers with "type": "http" and the URL.

2.2 Start Claude Code again:

claude

On startup, Claude Code detects .mcp.json and asks you to approve the new server. Approve it.

2.3 Inside Claude Code:

/mcp

Expected: context7 is now listed as connected. Drill in — you should see two tools (resolve-library-id, get-library-docs).

2.4 Ask it something:

What is the latest version of Astro? Use context7.

Expected: Claude Code asks permission to call the Context7 tool (first use of a new MCP tool always prompts), then returns an answer that reflects current docs — not whatever was in training data.

Step 3 — Add a user-scope server (5 min — optional if you don't have a Tavily key)

Goal: see what user scope looks like and confirm the file lives outside the project.

3.1 Exit Claude Code. From the shell:

claude mcp add --scope user --transport http tavily-remote "https://mcp.tavily.com/mcp?tavilyApiKey=YOUR_KEY"

Replace YOUR_KEY with a real Tavily API key (skip this step if you don't have one).

3.2 Confirm it landed in user scope:

cat ~/.claude.json | grep -A 4 tavily-remote

Note: MCP entries live in ~/.claude.json, not ~/.claude/settings.json (which is a separate file Claude Code uses for other settings). If grep returns nothing, double-check you ran the command with --scope user.

3.3 Confirm it's not in the project .mcp.json:

cat .mcp.json

Expected: still only Context7. The Tavily entry is per-user, not per-project — exactly the right shape for a personal API credential.

3.4 Start Claude Code, run /mcp. Expected: both context7 and tavily-remote are connected. Run /context, write down the new MCP percentage.

Step 4 — Strict scoped run (5 min)

Goal: see --strict-mcp-config cut MCP context to the minimum.

4.1 Exit Claude Code. In your editor, create .mcp.json.context7-only in the sandbox:

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

4.2 Start Claude Code with the strict scoped config:

claude --mcp-config .mcp.json.context7-only --strict-mcp-config

4.3 Inside Claude Code:

/mcp

Expected: only context7 is connected. Tavily is gone even though it's still in your user-scope file — --strict-mcp-config told Claude Code to ignore the inherited scopes.

4.4 Run /context. Expected: the MCP percentage drops compared to Step 3 — you've shed Tavily's tool definitions. Write the new percentage down next to the others.

Reflection: which scoping move (file change, strict flag, per-session disable) felt right for which use case? Re-read §4 if any of them feel unmotivated.

Step 5 — Install a plugin from the Anthropic demo marketplace (8 min)

Goal: see the plugin install flow end to end, and read source before installing.

5.1 Exit and restart Claude Code with no flags (claude) so you're back at the default config.

5.2 Inside Claude Code:

/plugin

5.3 Choose Browse and install plugins, then Add marketplace. Paste:

https://github.com/anthropics/claude-code

Expected: Claude Code locates .claude-plugin/marketplace.json in that repo and loads the catalogue. (This is the demo marketplace, distinct from the official claude-plugins-official marketplace which Claude Code auto-loads without needing to be added.)

5.4 Before installing anything, open https://github.com/anthropics/claude-code/tree/main/plugins/commit-commands in your browser. Skim plugin.json and any command files. Confirm what this plugin does and what it touches.

5.5 Back in Claude Code, pick commit-commands and Install. Wait for completion.

5.6 Verify:

/plugin list

Expected: commit-commands is listed and marked enabled.

5.7 Try one of the commands the plugin shipped. Plugin commands are namespaced — type /commit-commands: and let autocomplete show what's available. The exact command names come from the plugin's plugin.json name field; don't guess at a bare command like /commit.

Step 6 — Reload and tear down (3 min)

6.1 Inside Claude Code, run /reload-plugins. Expected: if you'd edited the plugin's files, Claude Code would pick up the changes. Here nothing changed, so the reload is a no-op confirmation.

6.2 Remove the project-scope MCP config so the sandbox starts clean next time:

rm .mcp.json .mcp.json.context7-only

6.3 (Optional) Remove the user-scope Tavily entry:

claude mcp remove --scope user tavily-remote

6.4 (Optional) Uninstall the plugin from inside Claude Code:

/plugin uninstall commit-commands@claude-code-plugins

Or from the shell:

claude plugin uninstall commit-commands@claude-code-plugins

Verify with /plugin list that it's gone. (Current Claude Code docs ship uninstall as a documented, reliable command — the late-2025 book mentions an uninstall bug, but that's been resolved.)

Success checklist

• [ ] /mcp lists at least Context7 after Step 2; no servers connected after Step 6.2 baseline.
• [ ] .mcp.json exists in the sandbox containing Context7 (Step 2).
• [ ] User-scope Tavily entry visible in ~/.claude.json and not in .mcp.json (Step 3) — if you have a Tavily key.
• [ ] Three /context measurements recorded: baseline, with project + user MCP, with --strict-mcp-config. Each one strictly smaller than the previous on the MCP block.
• [ ] At least one Context7 tool call succeeded (Step 2.4).
• [ ] One plugin installed, listed, and one of its commands run (Step 5).

Reflection prompts

• Which scope (local / project / user) would you have picked for Context7 in a real project, and why?
• The two /context percentages you measured before and after --strict-mcp-config — what's the gap, in absolute tokens (multiply by your model's context size)?
• The plugin you installed — what would have been the manual equivalent? List the commands / files you would have copied by hand.

Common pitfalls

• Forgetting --strict-mcp-config. --mcp-config <file> adds the file to whatever the three scopes (local, project, user) already provide. To load only the file you named, you need both flags. This is the single most common surprise in this chapter.
• Pasting API keys into .mcp.json. .mcp.json is meant to be committed. Live API keys do not belong there. Use ${API_KEY} placeholders or move the entry to user scope.
• Forgetting to restart after editing .mcp.json by hand. Most MCP changes are picked up at session start, not mid-session. If you edited .mcp.json while Claude Code was running, exit and re-launch.
• Installing a plugin you didn't read. Plugins ship arbitrary code, MCP servers, and hooks. Open the source on GitHub before installing — especially for plugins from marketplaces you don't already trust.
• Confusing /plugin with /mcp. /plugin manages plugins (which can include MCP servers as part of their bundle). /mcp manages MCP servers directly. The plugin you installed might add MCP servers that then show up in /mcp — that's expected.
• Typing a plugin's bare slash command and not finding it. Plugin commands are always namespaced /<plugin-name>:<command>. Hit / and look for the plugin's name as a prefix in the autocomplete list. If you type /<command> without the namespace, the autocomplete won't find it.

Knowledge check — try the quiz

A short six-question quiz is at the end of this chapter — five questions grounded in the book, one synthesis question on code-execution-against-MCP. Passing score is 5 out of 6.

Further reading & enrichment sources

The book is the primary source for this chapter. The following references were used silently throughout the lesson to verify, update, and extend the book's content. Each link is current at the time of writing.

Official MCP protocol (Linux Foundation, formerly Anthropic):

• Introduction — what MCP is, in one page.
• Architecture overview — hosts, clients, servers, the JSON-RPC data layer, and the transport layer.
• Transports specification — stdio and Streamable HTTP.
• Tools primitive, Resources, and Prompts.
• Official MCP servers registry — searchable catalogue.
• Reference MCP servers on GitHub.

Claude Code MCP and plugin docs:

• Connect Claude Code to tools via MCP — full Claude Code MCP reference (scopes, .mcp.json, ~/.claude.json, authentication, troubleshooting).
• Connect to MCP servers quickstart — step-by-step add and connect.
• Create plugins — authoring overview.
• Plugins reference — plugin.json schema, directory layout, validation.
• Plugin marketplaces — marketplace.json, distribution.
• Discover and install plugins — /plugin UI, /reload-plugins.

Anthropic announcements and engineering:

• Introducing the Model Context Protocol — the original Nov 2024 announcement.
• Donating MCP and establishing the Agentic AI Foundation — the Dec 2025 governance change.
• Code execution with MCP: Building more efficient agents — Anthropic's framing of the code-execution approach; the lesson's §7 leads with this post.
• Effective context engineering for AI agents — the broader argument behind §5.
• Writing effective tools for AI agents — guidance for MCP server authors.
• Equipping agents for the real world with Agent Skills — context for how Skills sit alongside MCP inside Claude Code.

Cloudflare CodeMode (parallel work to Anthropic's code-execution-with-MCP):

• Code Mode: the better way to use MCP — the original Sep 2025 post.
• Code Mode: give agents an entire API in 1,000 tokens — Feb 2026 follow-up.
• Cloudflare Agents SDK — CodeMode reference — implementation details.

Marketplace and example plugins:

• anthropics/claude-code repo — contains .claude-plugin/marketplace.json and the source for the official demo plugins (commit-commands, feature-dev, pr-review-toolkit, code-review, agent-sdk-dev, plugin-dev, security-guidance, frontend-design, and more).