MCP, the Model Context Protocol, is how Claude Code reaches tools outside your codebase. Once a server is connected, Claude can read your issue tracker, query a database or call a service by itself instead of working from whatever you paste in. This guide covers how to add a server, which scope to pick, and what to check when it does not connect. The commands come from the Claude Code MCP docs.
What is the difference between Claude Code and MCP?
This question comes up a lot, so here is the short version. Claude Code is the agent: it reads your code, runs commands and makes changes. MCP is a standard way to plug extra tools into an agent like that. An MCP server is a small program or web service that exposes some tools, such as "search tickets" or "run a query," and Claude Code is the client that calls them. You do not need MCP to use Claude Code. You add a server when you want Claude to work with something it cannot reach from the terminal alone.
How to add an MCP server to Claude Code
Every server is added with claude mcp add. The form depends on where the server runs.
A remote server over HTTP
Most hosted services give you a URL. Add it with the HTTP transport:
claude mcp add --transport http <name> <url>
If the service wants an API key in a header rather than a sign-in, pass it with --header:
claude mcp add --transport http <name> <url> --header "Authorization: Bearer <your-key>"
There is also an SSE transport (--transport sse), but Anthropic marks it as deprecated. Use HTTP whenever a server offers it.
A local server that runs on your machine
Some servers are a command that Claude Code starts for you, often an npx package. Everything after the -- is the command and its arguments:
claude mcp add <name> -- <command> [args...]
For example, a server that needs an API key in its environment:
claude mcp add --env API_KEY=<your-key> my-server -- npx -y <package-name>
The -- matters. Without it, Claude Code tries to read the server's own flags as its own.
Adding from JSON or from Claude Desktop
If a vendor gives you a JSON config block, claude mcp add-json <name> '<json>' takes it as is. If you already set servers up in Claude Desktop, claude mcp add-from-claude-desktop copies them over.
Local, project or user scope
Every server is added at one of three scopes. Pick with --scope local, --scope project or --scope user.
| Scope | Who gets it | Where it is stored |
|---|---|---|
| Local (the default) | Only you, only in this project | ~/.claude.json |
| Project | Everyone who works in the repo | .mcp.json in the project root |
| User | Only you, in every project | ~/.claude.json |
Local is the default, which surprises people who add a server in one repo and then cannot find it in another. If you want a server everywhere, add it with --scope user.
Project scope writes a .mcp.json file you can commit, so the whole team gets the same servers. For safety, Claude Code asks you to approve project-scoped servers before using them in an interactive session. Keep keys out of that file, since it is shared.
Signing in with /mcp
Many remote servers use OAuth instead of a pasted key. After adding one, type /mcp inside Claude Code. It shows each server's status and lets you sign in to the ones that need it, which opens a browser window. /mcp is also the first place to look when a server seems to be missing.
Managing your servers
| Command | What it does |
|---|---|
claude mcp list | Lists every server Claude Code knows about |
claude mcp get <name> | Shows the details for one server |
claude mcp remove <name> | Removes a server |
/mcp | Shows status inside a session and handles sign-in |
When a server will not connect
- It does not appear at all. Check the scope. A local server added in another folder will not show up here. Run
claude mcp listfrom the project you are in. - It shows as needing authentication. Run
/mcpand sign in. - It starts too slowly and times out. Local servers that install packages on first run can be slow. The
MCP_TIMEOUTsetting raises the startup timeout. - A project server is ignored. You may have declined the approval prompt for
.mcp.json. Check/mcp. - Results get cut off. Claude Code warns when a tool returns more than 10,000 tokens and limits output to 25,000 tokens by default. Set
MAX_MCP_OUTPUT_TOKENShigher if a server legitimately returns large results, such as long query output.
An example: adding FixMyPrompt
FixMyPrompt is an MCP server, so it makes a concrete example. It keeps what your AI worked out as memories: the steps, commands and checks that fixed something, so the next session follows them instead of starting over. We make it, so treat this as one example among many.
It is a remote server that signs in with OAuth, so it takes one command and one sign-in:
claude mcp add --transport http fmp https://fixmyprompt.net/api/mcp
Then type /mcp in Claude Code and sign in to fmp. After that you can say "save how you fixed that to memory" when Claude gets something right, and later "use fmp to find how we deploy staging" to get it back. Add --scope user if you want it in every project rather than just the current one. The setup page also covers Codex and Cursor.
Keep the list short
Every connected server adds its tools to what Claude has to choose from in each session. A handful of servers you actually use beats a long list you added once to try. Remove the ones you stopped using with claude mcp remove, and if you want Claude to remember how it set up or fixed a server, that is a good first thing to save as a memory.