- An MCP server gives Claude Code tools for a system outside your repo. MCP itself is an open standard, so the same server works in other AI applications.
- One command adds a server:
claude mcp add. The scope flag decides which file it is written to and who else gets it. - Two config files matter:
~/.claude.jsonfor local and user scope, and.mcp.jsonin the project root for servers you share with a team. - A connected server is not a capable one. Every connector we use has a limit that only showed up when we checked its output against the real system.
- Context cost is lower than it used to be, because tool definitions are deferred by default. It is not zero, and tool results are the larger cost.
- Treat every server as code you are running and content you are trusting. A server that fetches outside content is a route for prompt injection.
Most of what a business wants from an AI agent sits outside the code repository: the inbox, the calendar, the CRM, the site builder, the design file. Claude Code MCP servers are how the agent reaches those systems. Adding one takes a single command. Knowing where the configuration went, who else it affects and what the server can do once it is in is the part worth learning.
This guide walks through setup using today's commands, verified against the documentation and against claude mcp --help on Claude Code 2.1.327 in November 2026. Then it covers what our own connected setup taught us about the limits. For the wider picture of what agents are, see AI agents explained.
What is MCP?
MCP is the Model Context Protocol. Its own documentation defines it as "an open-source standard for connecting AI applications to external systems" and offers the comparison everyone repeats: "Think of MCP like a USB-C port for AI applications."
The architecture has three participants:
- The host is the AI application. Claude Code is one.
- A client is the component inside the host that holds the connection to one server. The host creates one client per server.
- A server is a program that provides context to clients.
A server can expose three kinds of thing. Tools are functions the model can call, such as running a query or creating a draft. Resources are data the application can read, such as a file or a database schema. Prompts are reusable templates. In Claude Code, tools are what you will use most.
Servers come in two shapes, and the difference matters for security and setup:
- Local servers run as a process on your machine and talk over standard input and output (the stdio transport). They suit tools that need direct access to your system.
- Remote servers run on someone else's platform and talk over HTTP (the Streamable HTTP transport). They typically serve many clients and use OAuth for sign-in.
Because MCP is a standard, a server is not tied to one product.
Claude Code MCP setup, step by step
Everything goes through the claude mcp command in your shell. These are the subcommands in the installed CLI as of November 2026:
| Command | What it does |
|---|---|
claude mcp add |
Add a server |
claude mcp add-json |
Add a server from a JSON string |
claude mcp add-from-claude-desktop |
Import servers from Claude Desktop (Mac and WSL) |
claude mcp list |
List configured servers with a health status |
claude mcp get <name> |
Show one server's details |
claude mcp login <name> / logout <name> |
Sign in to a server, or clear stored OAuth credentials |
claude mcp remove <name> |
Remove a server |
claude mcp reset-project-choices |
Reset approvals for servers in .mcp.json |
claude mcp serve |
Run Claude Code itself as an MCP server |
Step 1: add a remote server. HTTP is the recommended transport for remote servers. The documentation's own example:
claude mcp add --transport http notion https://mcp.notion.com/mcp
The pattern is claude mcp add --transport http <name> <url>. If the service uses a static token instead of OAuth, pass it as a header:
claude mcp add --transport http secure-api https://api.example.com/mcp \
--header "Authorization: Bearer your-token"
Some services still offer only the older SSE transport, which the docs mark as deprecated. Recent versions try HTTP first and fall back to SSE on their own; --transport sse forces it.
Step 2: or add a local server. A stdio server is a command Claude Code starts for you:
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
-- npx -y airtable-mcp-server
The double dash is the part people get wrong. Everything before -- is an option for Claude Code. Everything after it is the command that runs the server, passed through untouched.
Step 3: sign in. For a server that uses OAuth, start Claude Code, type /mcp, pick the server and follow the browser flow. From the shell, claude mcp login <name> does the same. Tokens are stored and refreshed for you.
Step 4: check it.
claude mcp list
Each server gets a status such as ✔ Connected, ! Needs authentication or ✘ Failed to connect. A claude mcp add that worked prints an Added line, which only means the configuration was written. The list is what tells you whether the connection works.
Step 5: prove it with something read-only. Ask Claude to fetch one record you can check by eye. Tools from MCP servers are named mcp__<server>__<tool>, and you will see that name in the permission prompt the first time each one is used.
MCP config file location and scopes
The --scope flag decides where the entry is written and who sees it.
| Scope | Loads in | Shared with team | Stored in |
|---|---|---|---|
local (the default) |
The current project only | No | ~/.claude.json, under that project's path |
project |
The current project only | Yes, through version control | .mcp.json in the project root |
user |
All your projects | No | ~/.claude.json |
A trap the docs call out by name: MCP "local scope" is stored in your home directory, in ~/.claude.json. It has nothing to do with .claude/settings.local.json, which holds general settings.
A project-scoped add looks like this:
claude mcp add --transport http shared-server --scope project https://example.com/mcp
and produces a .mcp.json you can read and commit:
{
"mcpServers": {
"shared-server": {
"type": "http",
"url": "https://example.com/mcp"
}
}
}
Three rules about this file are worth knowing before you share one.
- A remote entry needs a
type. An entry with aurland notypeis read as a stdio server, reported as a configuration error and skipped.streamable-httpis accepted as an alias forhttp, so JSON copied from a server's own docs works. - Secrets stay out of it. Values in
command,args,env,urlandheaderscan reference environment variables as${VAR}or${VAR:-default}:
{
"mcpServers": {
"api-server": {
"type": "http",
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": {
"Authorization": "Bearer ${API_KEY}"
}
}
}
}
- Teammates are asked first. In an interactive session, Claude Code prompts for approval before using a server from a
.mcp.jsonit has not seen approved. A cloned repository cannot approve its own servers.
Which scope to choose:
- Local for anything experimental, anything with a credential in the entry, and anything only you need in one project. It is the default for a reason.
- Project for servers the whole team needs in that repository, with tokens supplied through environment variables.
- User for personal tools you use everywhere, such as a site builder or a design tool.
When the same server name is defined in more than one place, Claude Code connects once, using the highest of: local, then project, then user, then plugin-provided servers, then connectors from claude.ai. The whole entry from the winning source is used; fields are not merged.
Connectors from claude.ai and signing in
There is a second way servers arrive, and it explains why claude mcp list may show servers you never added. If you are logged in to Claude Code with a claude.ai account, the connectors you have set up there (at claude.ai/customize/connectors) are available in Claude Code automatically. They show in /mcp marked as coming from claude.ai.
A few behaviours from the MCP documentation explain most connector confusion:
- Connectors only load with a claude.ai subscription login. If an API key or a third-party provider is the active authentication method, they do not appear.
/statusshows which method is active. - Some connectors cannot be added by hand. The docs name mail, calendar and office-suite connectors whose identity providers only accept claude.ai's registered redirect. You connect those on claude.ai and they appear in Claude Code.
- Non-interactive runs cannot sign in. A
claude -prun has no/mcppanel. Complete the sign-in from an interactive session first. - Removing is not revoking.
claude mcp removedeletes the stored tokens locally. To revoke them at the issuer, where that is supported, runclaude mcp logout <name>first.
Where a session runs changes what it can reach. Our notes from an earlier check record that a cloud session started from the terminal brought the repository's .mcp.json with it but not the servers we had added locally with claude mcp add. Today's docs point the same way: connectors for cloud sessions are passed in by the cloud host, and cloud scheduled tasks have connectors configured per task. Plan for the agent's reach to differ between your laptop and the cloud.
What our own setup looks like, and where connectors fall short
Running claude mcp list on our main machine today shows seven servers. Five are claude.ai connectors: mail, calendar, file storage, documents and a media-generation service. Two were added with claude mcp add over HTTP: a design tool and a site-builder platform. One of the seven reported ! Needs authentication. A browser-automation extension is connected as well, as a built-in integration.
That list reads like broad capability. In practice each connector has an edge, and none of the edges were visible from the tool list. We found them by checking results against the real system.
The mail connector cannot produce a client-ready draft. We tested it by decoding the raw message of drafts it created. Every image was removed, including inline ones, so a signature graphic could not survive. Every link, including bare domain text, was rewritten into a tracking redirect that expires after 24 hours, and the rewrite was saved into the draft itself. There was no scheduled send. For any email a person will send to a client, we hand the operator a compose link that opens a normal draft in their own mail client instead.
The site-builder server exists because the plain API stops short. With an ordinary site API token we could update page titles and descriptions but not custom code, which the vendor reserves for OAuth apps. The vendor's official MCP server is an OAuth app, so it is the documented route for writing things like canonical tags and structured data. It authorises one workspace at a time, and installing the vendor's companion app does not by itself give Claude any tools. As we write this, that server is the one showing ! Needs authentication, and we have not confirmed its full tool list in use. We would rather say so than describe features from a vendor page.
The media-generation connector is tied to one account and does not expose everything. A model we use from the vendor's web interface was missing from the connector's catalogue, and the connector rejected it by name. Large batches hit rate limits. Because every call spends credits, our rule is a cheap still image approved by a person before any video generation.
The pattern across all three: a connector is a subset of a product, chosen by the vendor, with behaviours of its own. Three habits follow.
- Test output at the destination, not in the transcript. The draft looked fine in Claude's summary. The raw message did not.
- Keep a non-MCP route for anything that matters. A command-line tool or a direct API call is often more complete than the connector.
- Write the limit down where the agent will read it, so the next session does not rediscover it. This is the kind of durable fact that belongs in Claude Code memory.
How many MCP servers is too many?
The old answer was "a handful", because every tool's full definition was loaded into context at the start of each session. As of November 2026 that has changed. With tool search, which is on by default, the docs say "only tool names and server instructions load at session start", and tool definitions are fetched when Claude needs them. Claude Code sets no fixed cap on tools per server. The practical limit is your context budget.
That lowers the cost. It does not remove it:
- Names and instructions still load. One of our connectors alone lists well over a hundred tool names, plus a long block of server instructions, in every session whether or not the task involves it.
- Results are the real cost. A tool that returns a large payload fills context far faster than its definition did. Claude Code warns when an MCP tool output passes 10,000 tokens. The default maximum is 25,000 tokens, adjustable with the
MAX_MCP_OUTPUT_TOKENSenvironment variable, and larger results are saved to a file for Claude to read as needed. - More tools means more wrong turns. Two servers that can both "search files" give the model a choice it can get wrong.
What to do about it:
- Run
/contextto see what is taking space, and/usage, which on subscription plans breaks usage down by MCP server among other things. - Open
/mcpand toggle off servers you are not using in this project. The choice is recorded per project and the configuration is kept. - Prefer a CLI where one exists. The cost guidance says tools like
gh,awsandgcloudare "still more context-efficient than MCP servers because they don't add any per-tool listing." - Scope narrowly. A server only one project needs should be local or project scope, not user scope.
- For delegated work, a subagent definition can withhold a server's tools with a
disallowedToolsentry.
A workable rule: a server earns a permanent place when you would otherwise be copying data out of that system into the chat several times a week. Anything less, connect it for the job and switch it off after.
A security checklist
Anthropic's security page says two things that should set your posture. It encourages "either writing your own MCP servers or using MCP servers from providers that you trust." And although connectors are reviewed against listing criteria before entering the directory, Anthropic "does not security-audit or manage any MCP server." The MCP page adds a warning that servers which fetch external content "can expose you to prompt injection risk": text on a web page, in an email or in an issue comment can be written to look like instructions.
The checklist we work from:
- Know who runs the server. Prefer the vendor's own server over a third-party wrapper for the same product.
- Read before you run a local server. A stdio server is a program started on your machine. Check what the command installs and executes.
- Give it the smallest account that works. A read-only login or a narrowly scoped token for the server's own credentials. An agent with a full-admin token can do full-admin damage.
- Keep tokens out of the repository. Use
${VAR}expansion in.mcp.json, or local scope. - Review
.mcp.jsonin any repository you clone. Interactive sessions ask before using those servers. Non-interactiveclaude -pruns load them without asking. - Treat content from outside as untrusted. Anything a server fetches from the web, an inbox or a ticket queue is data, not instructions. Keep write actions behind a permission prompt when the session is also reading outside content.
- Put a person in front of anything outward-facing. Sending mail, publishing a page and spending credits get explicit confirmation. A deny rule in settings can block a single tool or a whole server outright.
- Remember reviewing
.mcp.jsonis not the whole picture. Servers can also come from user scope, claude.ai connectors and plugins. - Revoke when you are done.
claude mcp logout <name>, thenclaude mcp remove <name>.
If you want a rule enforced instead of remembered, a PreToolUse hook can match MCP tools by name and refuse a call. We cover the mechanics in our guide to Claude Code hooks.
What to take from this
Adding Claude Code MCP servers is the easy part: one command, one scope decision, one sign-in. The work is everything after. Find out what each server cannot do, keep the set small enough that the agent chooses well, and decide in advance which actions need a person.
The setups that last look boring: a few servers, tokens in the environment, read access by default, and a written note of every limit you have hit. That is also how the scheduled agents in our AI SEO agent write-up stay trustworthy: narrow access, checked output. If you are choosing between a connector and building directly on the API, how to build AI agents with Claude covers the other route.
Connecting an agent to the systems a business runs on is most of what our AI integration service involves. If you have a tool you want an agent to reach and are not sure a connector is the right route, tell us which systems are involved.
Common questions
What are Claude Code MCP servers?
They are programs that give Claude Code access to systems outside your repository: an issue tracker, a database, a mail account, a design tool. Each one speaks the Model Context Protocol, an open standard, so the same server works with other AI applications too. Once a server is connected, its tools appear to Claude alongside the built-in ones such as Read and Bash, and Claude can call them during a task instead of working from what you paste into the chat.
How does Claude Code MCP config work?
Each server is one entry under an mcpServers key: a name, a type (http, sse or stdio), and either a url with optional headers or a command with args and env. You rarely write it by hand. The claude mcp add command writes the entry for you into the right file for the scope you choose. To use a JSON entry copied from a server's own documentation, claude mcp add-json takes the name and the JSON string directly.
What is the Claude Code MCP config file location?
As of November 2026 there are two files. Local-scope and user-scope servers are stored in ~/.claude.json in your home directory: local ones under the entry for the project you added them from, user ones available to every project. Project-scope servers are stored in .mcp.json at the project root, which is meant to be committed. Note that MCP local scope is not .claude/settings.local.json; that file holds general settings, not servers.
What does Claude Code MCP setup involve?
Four steps. Add the server with claude mcp add, choosing a transport and a scope. Sign in if it needs it, by running /mcp inside Claude Code or claude mcp login with the server name in your shell. Check it with claude mcp list, which prints a health status beside each server. Then ask Claude to do something small and read-only with it, and confirm the result against the real system before you trust it with writes.
How do I use claude mcp add?
For a remote server: claude mcp add --transport http, then a name, then the URL. For a local server: claude mcp add, the name, a double dash, then the command that starts it, with --env KEY=value for any variables it needs. Add --scope user to have it in every project or --scope project to write it to .mcp.json for the team. With no scope flag it defaults to local: this project only, private to you.
What goes in a Claude Code MCP JSON file?
A .mcp.json file holds one object with an mcpServers key. Each server inside it has a type and either a url, for remote servers, or a command and args, for local ones. Values can reference environment variables as ${VAR} or ${VAR:-default}, which lets a team share the file without committing tokens. A remote entry needs a type: an entry with a url and no type is treated as a configuration error and skipped.
What is MCP?
MCP stands for Model Context Protocol. Its own documentation defines it as an open-source standard for connecting AI applications to external systems, and compares it to a USB-C port for AI applications. A server can expose three kinds of thing: tools, which are functions the model can call; resources, which are data it can read; and prompts, which are reusable templates. Servers run either locally as a process on your machine or remotely over HTTP.

