# MCP connects tools, and every tool costs context

MCP gives Claude tools that live outside your machine's built-ins. The setup is one command. The real decisions are which scope to use and whether a plain CLI would have done the job for free.

## 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:

```bash
claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --transport stdio myserver -- python server.py --port 8080
```

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.

**Question:** You add the same server name at the user scope and the project scope with different settings. What happens?

- The settings are merged field by field
- The user entry wins and the project one is ignored
- The project entry wins whole, with no merging
- Claude asks you each time

**Answer:** The project entry wins whole, with no merging. Precedence runs local, project, user. The winning entry is used as it is, with no field merging.


## 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".

> **Prefer a plain CLI when one exists**
For GitHub, `gh` already works from the shell and costs no context at all. Reach for MCP when you need structured tools or OAuth, not by default.


## 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.

> **Silent skips and half-removals**
An entry that has a `url` but no `type` is treated as stdio and skipped silently, so add `type`. And `claude mcp remove` deletes local tokens without revoking them. Run `claude mcp logout <name>` first.


## 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.

> **Count the cost**
Run `/mcp` and look at what is connected. For each server, ask whether you used it this week. Remove or narrow the ones you did not, and check whether a CLI you already have does the same job.


**Question:** Which is the strongest reason to choose MCP over a plain CLI?

- MCP is always faster
- You need structured tools or OAuth
- A CLI cannot read secrets
- MCP uses no context

**Answer:** You need structured tools or OAuth. A CLI such as gh costs no context. MCP earns its place when you need structured tools or OAuth sign-in.