Skip to content
Claude Code MCP: How to Add, Scope and Fix MCP Servers
← All postsAI Tools

Claude Code MCP: How to Add, Scope and Fix MCP Servers

November 17, 2026·FixMyPrompt Team·7 min read
Share

How to add an MCP server to Claude Code with claude mcp add, the difference between local, project and user scope, signing in with /mcp, and what to check when a server will not connect. Commands taken from Anthropic's docs.

#claude code mcp#claude mcp add#mcp server#model context protocol#claude code#.mcp.json

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.

ScopeWho gets itWhere it is stored
Local (the default)Only you, only in this project~/.claude.json
ProjectEveryone who works in the repo.mcp.json in the project root
UserOnly 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

CommandWhat it does
claude mcp listLists every server Claude Code knows about
claude mcp get <name>Shows the details for one server
claude mcp remove <name>Removes a server
/mcpShows 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 list from the project you are in.
  • It shows as needing authentication. Run /mcp and sign in.
  • It starts too slowly and times out. Local servers that install packages on first run can be slow. The MCP_TIMEOUT setting 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_TOKENS higher 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.

Try it on the prompt that sent you here

Paste the prompt that misbehaved and see what is weak in it.

The weak spots and fixes are tuned to this goal.

0 of 5,000 characters

No prompt handy? Try one:

Found this useful? Share it.

Share

Read next

Run a free QA on your own prompt

Get a structured score, specific issues, and a rewritten prompt in seconds.

Run free QA