MCP connects tools, and every tool costs context

What an MCP server adds

Out of the box Claude can read files, search, edit and run shell commands. It cannot see your Notion pages, your issue tracker or your database unless something gives it a way to.

An MCP server is that something. It exposes extra tools to Claude, and Claude calls them the same way it calls any other tool in the loop. The server can run as a local process (stdio), or remotely over http (also written streamable-http), or sse/ws.

Adding one takes a single command:

Everything after the -- goes to the server command untouched. That is how a flag like --port reaches your server instead of being read by Claude Code.

Three scopes

Where you add a server decides who gets it.

• local, the default: stored for this project inside ~/.claude.json, visible only to you
• project: written to .mcp.json at the repo root and shared through git
• user: available in all your projects

Pick with --scope project|user|local. If the same name exists in several scopes, the order is local, project, user, plugin, then claude.ai connectors. The winning entry is used whole. Fields are not merged between scopes.

For a shared .mcp.json, keep secrets out of the file. Reference environment variables with ${VAR} or ${VAR:-default}, and each teammate supplies their own value.

What it costs in context

Tools are not free to carry. Every tool has a name, a description and a schema, and a server with many tools could fill your context before you type a word.

Claude Code softens this: tool search is on by default, so only tool names load up front and the full definitions arrive when a tool is needed. That helps a lot, but it does not remove the cost. Output costs too. A tool result above 10,000 tokens produces a warning and is capped at 25,000 by default (MAX_MCP_OUTPUT_TOKENS changes it). Text results over 50,000 characters are saved to a file instead.

So the question to ask before adding a server is not "can it connect" but "what will it make me carry".

Running and fixing

/mcp shows the status of each server and /mcp reconnect <server|all> retries a connection. A dropped remote server gets five reconnect attempts with backoff starting at one second. A call still running after two minutes moves to a background task you can see in /tasks.

Two quiet traps are worth knowing.

Trusting what comes through

A server is code you run, and its tool results go straight into the model's context. Add servers you trust, scope them as narrowly as the job allows, and keep project-scope entries in .mcp.json where your team can read them in review.