Lesson 7 of 9 · Claude Code

MCP servers

Claude Code ships with a fixed set of tools: read, edit, run a command, search the web. An MCP server is how you hand it one more. The add command takes ten seconds. Choosing where the server lives, and whom you are trusting when you do, is the part worth a lesson.

The Agents module covered what a tool is: a named action the model can request and the harness carries out. Claude Code's built-in tools cover files, shell commands, and the web. They do not cover your GitHub account, your analytics, your hosting dashboard, or a database. As of September 2026, MCP servers are the standard way to add those, and the same protocol has been adopted well beyond Claude.

MCP in plain English

MCP stands for Model Context Protocol. It is an open standard, first published by Anthropic and now governed outside it, that describes how an AI tool and an outside service talk to each other. Think of it as a standard wall plug. Before MCP, every AI product needed its own custom wiring for every service. With MCP, a service publishes one server, and any agent that knows the plug can use it.

An MCP server is the thing on the other end of the plug. It is a small program that exposes a list of tools, each with a name, a description, and the inputs it takes. When Claude Code connects to a server, those tools join the menu the model already has. A GitHub server adds "list pull requests" and "read this issue." A browser server adds "open this URL" and "click this button." The model does not know or care that the tool came from outside. It just sees one more option and picks it when the job calls for it.

The servers this site's owner runs day to day fall into four categories, and they are a good picture of what people actually plug in: a source-control server for GitHub, a browser server that drives Chrome so Claude can look at a page the way a customer does, an analytics server for reading traffic numbers, and a hosting server for checking deployments. Each one replaced a copy-paste habit.

Two ways a server runs

A server is either a program on your machine or a service at a URL. The transport flag tells Claude Code which. There are two you will use:

http. The server is hosted somewhere and you give Claude Code its URL. Most vendor-run servers work this way. You add one with --transport http and the URL.
stdio. The server is a program Claude Code starts on your machine as a child process. You leave off the transport flag, since stdio is the default, and put the program's command after a -- separator. The official docs use a browser server as the example:

claude mcp add playwright -- npx -y @playwright/mcp@latest

There is a third transport, sse, still documented as of September 2026 but marked deprecated. If a vendor offers both, pick http. You will see sse only when connecting an older server that has not moved yet.

One rule the docs repeat and people miss: run claude mcp add in your terminal, not inside a Claude session. You are configuring the server before the conversation starts. Inside a session, /mcp is the command for checking, authenticating, and toggling servers you already added.

The three scopes and where each is stored

Every server you add lands in exactly one scope. The scope answers two questions: who can see the server, and in which projects it loads. The --scope flag sets it, and it is fixed once set. To move a server between scopes you remove it and add it again.

local is the default. The server loads only in the project where you added it and only for you. Claude Code writes it to ~/.claude.json under that project's path, so opening a different folder means the server is not there.
project writes to .mcp.json at the root of the repo. That file is meant to be committed. Everyone who clones the repo gets the same server, after Claude Code asks them to approve it the first time.
user also writes to ~/.claude.json, but under the top-level mcpServers key instead of a project entry. The server loads in every project you open and stays private to you.

The command shape is the same for all three:

claude mcp add --transport http <name> --scope <scope> <url>

The name is one you make up. Claude Code uses it to label the server's tools in its output and to refer to the server in later commands.

Pick who needs the server and where, get the scope

Who needs it?

Which projects?

Answer both questions above.

The example server is the Claude Code docs server from the official quickstart. It needs no sign-in, so it is safe to try. Commands verified against code.claude.com/docs as of September 2026.

A note on the fourth square of that picker. There is no scope that means "my whole team, every project." Project scope is per-repo by design. Organizations that want one server everywhere push it through managed settings, which is an admin feature this lesson does not cover.

Managing what you added

Four commands cover the day-to-day:

claude mcp list shows every configured server with a status: connected, needs authentication, failed to connect, or pending approval for a project server you have not accepted yet.
claude mcp get <name> shows one server in detail, including which scope holds it and the full URL or command. This is the first thing to run when a server misbehaves.
claude mcp remove <name> deletes it. If the same name exists in two scopes, the command refuses and asks you to add --scope so it knows which copy to delete.
/mcp, typed inside a session, opens a panel where you can see the same list, sign in to a server, reconnect one that dropped, or toggle one off without removing it.

Precedence. If the same server name is defined in more than one place, Claude Code connects once and uses the entry from the highest-ranked source. The order, highest first, is local, then project, then user, then servers that came from a plugin, then connectors from claude.ai. The whole entry wins. Fields are not merged across scopes, so a URL from your user entry never combines with a header from the project entry.

Signing in. Many hosted servers sit behind OAuth, the same browser sign-in you use for "log in with GitHub." You add the server by URL, run /mcp, pick the server, and choose Authenticate. A browser tab opens, you approve, and the token is stored securely and refreshed on its own. The same panel has a "Clear authentication" option to revoke it. As of September 2026 there is also claude mcp login <name> for doing the sign-in from the shell without opening a session.

Keys. Some servers take a static token instead of a sign-in. The official examples show passing it with --header or --env on the add command. Read that as a demonstration, not a habit. A literal key on the command line goes into your shell history, and a literal key typed inside a Claude session goes into the transcript file on disk. Two better options, both documented: put ${VAR} in the .mcp.json entry and let Claude Code expand it from your environment at start, or use the --client-secret flag, which prompts for the value with masked input instead of taking it as text. The settings and secrets lesson covers the full pattern.

Trust: the part people skip

A project .mcp.json from a repo you cloned is somebody else's code. A stdio entry in it is a command that will run on your machine. An http entry is a service that will see everything Claude sends it, and whose replies land in Claude's context, where they can carry instructions. That is why Claude Code asks before using any project-scoped server, and why the official docs say to verify you trust each server before connecting it.

Three mechanisms back that prompt up. First, workspace trust: the first time you run Claude Code in a new folder it asks whether you trust the folder. Until you say yes, the repo cannot approve its own servers. A committed enableAllProjectMcpServers setting in an untrusted folder is ignored and the server stays at pending approval. Second, claude mcp reset-project-choices wipes your yes and no answers so you can be asked again, useful after you rejected a server in a hurry. Third, disabledMcpjsonServers in a settings file rejects named servers from a project's .mcp.json outright, so you can keep a teammate's experimental server from ever starting on your machine without touching the shared file.

Do not confuse that last key with disabledMcpServers, which is the list /mcp writes to when you toggle a server off. The docs say plainly that the two are unrelated. One rejects servers from the project file. The other pauses servers you set up yourself.

The hard part, simply: which scope for whom

The analogy: a scope is a key to a door, and the question is not only who gets the key but whose house the door is on. Local and user scope are keys to your house. Project scope is a key you leave in the shared front hall, and anyone who walks in can add their own.

Worked example. A Hurricane rental company has a booking database and wants Claude Code to read it: which units are out this weekend, which deposits are unpaid. The owner runs the shop and a contractor does the website. Who gets what?

The owner adds the database server at user scope. It follows them into the website repo, the accounting scripts, and whatever they open next, and it never touches git. The credential stays on the owner's machine.

For the contractor, the owner writes a project scope entry in .mcp.json by hand, with the connection string as ${BOOKING_DB_URL} instead of the real value. The contractor clones, gets the approval prompt, says yes, and sets that variable to a read-only credential the owner issued. The contractor has the tool. They never see the owner's login.

Now the trust runs both ways. Anything the contractor commits to .mcp.json shows up on the owner's machine as a new approval prompt. The owner should read that diff the way they would read a stranger's script, because that is what it is.

Servers, connectors, and plugins

Three words that sound alike and are not. An MCP server is the thing you have been adding all lesson: a program or URL, registered with claude mcp add, stored in one of the two config files. A connector is claude.ai's name for a remote MCP server you attach to your account in the claude.ai settings, under Customize and then Connectors. As of September 2026, connectors you add there load automatically in Claude Code when you are signed in with that claude.ai account, and they show up in /mcp marked as coming from claude.ai. They do not load when you authenticate with an API key instead. On Team and Enterprise plans only an admin can add them, and a disableClaudeAiConnectors setting turns them off for Claude Code entirely.

A plugin, from lesson 6, can bundle a server. The plugin author declares it in a .mcp.json at the plugin root or inline in plugin.json. When you enable the plugin, Claude Code starts its servers on its own, and their tools appear next to the ones you configured by hand. You do not add or remove a plugin server with claude mcp commands. You install or uninstall the plugin. You can still toggle a plugin server off in /mcp if you want the plugin's skills without its tools.

The practical difference: servers are yours to configure and live in files you can read. Connectors are managed in a web UI and follow your account. Plugin servers follow the plugin. In the precedence list above both rank below anything you set yourself.

Try this yourself

Add one hosted server at user scope, confirm it, use it once, and take it out. The server is the Claude Code documentation server from the official quickstart. It needs no sign-in. Run the first two lines in your terminal, not inside a session:

claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp
claude mcp list

The add command prints the file it modified. The list should show claude-code-docs as connected. Now start a session with claude and type:

Use the claude-code-docs server to look up what MCP_TIMEOUT does

Approve the permission prompt the first time Claude calls the server. The tool call in the output is labeled with the server name, which is how you know the answer came through the server and not from Claude's own memory. Exit the session and clean up:

claude mcp remove claude-code-docs --scope user

Then run claude mcp list one more time and confirm it is gone. Every connected server puts its tool names into the context window at the start of each session, so the remove step is not just tidiness. That add, list, use, remove loop is the whole skill.

Next lesson8. Subagents and hooks

Last updated September 17, 2026