How to Add an MCP Server to Claude Code

To add an MCP server to Claude Code, run claude mcp add --transport http <name> <url> for a remote server, or claude mcp add <name> -- <command> for a local one. Pick a scope with --scope local, project or user, then run claude mcp list or /mcp to check that it connected.

What MCP does in Claude Code

MCP (Model Context Protocol) is an open standard that lets an AI app call outside tools. Claude Code is the client. An MCP server exposes tools Claude can call during a session, such as reading a database, searching docs, or placing an order. The protocol introduction is the short definition. People also search claude mcp, which covers more than the CLI. This page is about Claude Code only.

Claude Code is the command-line agent. MCP is how it reaches other systems. You can run Claude Code with no extra servers. Adding one gives Claude that server's tools next to the tools that already ship with the CLI. Commands, scopes, and limits below follow the Claude Code MCP docs. The quick start is the official short path.

Add an MCP server to Claude Code

HTTP is the recommended transport for remote servers. Use it for a URL you do not run yourself. Use stdio for a program on your machine. The same steps are what people mean by claude code add mcp.

Remote server over HTTP

Pass the transport, a name, and the URL. Add --header when the server expects a bearer token. -t is short for --transport, and -H is short for --header. The docs' own example is Notion at https://mcp.notion.com/mcp.

claude mcp add --transport http <name> <url>
# with a bearer token
claude mcp add --transport http <name> <url> --header "Authorization: Bearer <token>"
claude mcp add --transport http notion https://mcp.notion.com/mcp

The header is stored with the server entry. Keep a real token on your machine. Do not paste it into a chat message. If the server expects a different header name, pass that name instead of Authorization.

Local server over stdio

A local server is a command Claude Code starts for you. Everything after -- is that command, not a Claude Code flag. -e is short for --env.

claude mcp add [options] <name> -- <command> [args...]
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server

Without the dashes, Claude Code tries to parse the server's flags as its own. In the Airtable line, --env sets AIRTABLE_API_KEY for the server process. Leave another option, such as --transport stdio, between --env and the name. If the name sits directly after --env, the CLI reads it as another KEY=value pair and rejects the command.

SSE (deprecated)

--transport sse still exists but is deprecated. Prefer HTTP. Recent Claude Code versions try HTTP first and fall back to SSE when the server does not accept HTTP.

Add from JSON

claude mcp add-json <name> '<json>' writes a full entry in one step. Use it for a WebSocket server too. The --transport flag does not accept ws, so set type to ws in the JSON. That entry takes the same url and headers fields as HTTP.

claude mcp add-json example '{"type":"http","url":"https://mcp.example.com/mcp"}'

Two gotchas from the docs: type accepts streamable-http as an alias for http, and an entry with a url but no type is a configuration error. Claude Code reads a missing type as stdio, skips that server, and reports it. Set type to http, sse, or ws whenever the entry has a url.

Choose a scope: local, project or user

Pass --scope local, project, or user. The short form is -s. Local is the default when you leave the flag off.

If the same name exists in more than one place, local wins, then project, then user, then plugins. The whole entry from the winning source is used. Entries are not merged. Put personal tokens in user or local scope. Put shared definitions with no tokens in project scope.

Share servers with your team in .mcp.json

A project file can name a secret without committing it. Claude Code expands ${VAR} and ${VAR:-default} in command, args, env, url, and headers. Set the variable in the shell before you start Claude Code. An unset variable with no default is left as the ${VAR} text, and claude mcp list warns. A variable set to an empty string counts as set, so the default is not used.

{
  "mcpServers": {
    "example": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${EXAMPLE_API_KEY}" }
    }
  }
}

Project servers show as Pending approval until you trust the workspace. That is a safety feature, not a bug. Claude Code does not load servers from a project's .mcp.json until you open the project and approve them. A cloned repo cannot start servers you did not choose. After you approve, check /mcp.

Manage your MCP servers

• claude mcp list shows every server and its status, such as connected, needs authentication, or failed to connect.
• claude mcp get <name> shows one entry, including the issue line when a connection failed.
• claude mcp remove <name> deletes it. If the same name exists in more than one scope, pass --scope so you remove the entry you mean.
• /mcp inside a session shows status, handles OAuth sign-in, and lets you disable a server without deleting it.

A successful add prints an Added line. That means the config was written, not that the token was accepted. Check claude mcp list or /mcp for a connected status. A bad token shows a failed connection, often with the HTTP status the server returned.

Limits and troubleshooting

• Slow startup: raise MCP_TIMEOUT, for example MCP_TIMEOUT=10000 claude, which sets a 10-second startup timeout.
• Slow tools: set a per-server "timeout" in milliseconds. It overrides MCP_TOOL_TIMEOUT for that server. A value below 1000 is ignored.
• Big outputs: Claude Code warns above 10,000 tokens of tool output and caps at 25,000 by default. Change the cap with MAX_MCP_OUTPUT_TOKENS. The warning line stays fixed. Unless the server raises a tool's own limit, text results longer than 50,000 characters are saved to a file anyway.
• Server not found: check the name and the scope with claude mcp list, and remember the precedence above.
• Token not sent: check environment variable expansion. In a remote url or header, credential variables such as ANTHROPIC_API_KEY read as empty, and a default on that name is ignored. Copy the value into a variable with a name of your own, then reference that name. Any other unset variable still loads the server, and claude mcp list names it.

Before you connect a server, check what it can do

The docs say: "Verify you trust each server before connecting it." Run through this list for any server, whoever published it.

• Who runs it, and can you read what the URL or the command actually does?
• Which tools only read, and which tools can write or spend?
• What can the token do, and can you revoke it on its own?
• Are limits enforced on the server, or only written into the prompt?

Servers that fetch outside content can carry instructions back into the session. Treat fetched pages and messages as data, not as orders. See the MCP security best practices, OWASP LLM06 Excessive Agency for write-capable tools, and OWASP LLM01 for prompt injection. MCP for trading covers how trading servers split read tools from write tools. The directory of crypto trading MCP servers is a list, not a ranking.

Worked example: connect a trading MCP server (Moby)

Here is what a write-capable server looks like in practice. The Moby MCP connector can research tokens and place trades, so the checklist above matters. One agent, with its own wallet, separate from the main in-app wallet. The full Claude Code setup for Moby has the project file that keeps the key in an environment variable. Assistants can also read agents.md.

1. Create a Moby Agent key in the Moby app: Agent tab, then Connect, then your platform. Keys start with moby_agent_. You can keep up to 5 active keys. Rotate or revoke one in the app. The key is not a wallet private key.
2. Export it in the shell that starts Claude Code. Never paste a key into a chat message.
3. Add it at user scope with the command below. It is the command on the Claude Code setup page. Replace the placeholder on your machine before you run it. The command stores that header value.
4. Check with claude mcp list or /mcp.
5. First prompt: "Show my Moby guardrails and balances." Use read tools first.

export MOBY_API_KEY="moby_agent_..."
claude mcp add --transport http moby https://mcp.moby.win/mcp --header "Authorization: Bearer moby_agent_..." --scope user

-s user is the short form of --scope user. User scope keeps the key out of the repo.

Why server-side limits matter here

This server can spend money, so the trust checklist matters more. You set your agent's limits on max per trade, daily buy volume and market-cap range from the Moby app, and Moby checks them server-side on every buy your agent makes. The agent cannot withdraw, transfer or send funds. There is no tool for it. Moby refuses agent buys on red-rated tokens. Base limits shown in the app are up to 6 trades a minute and 200 a day. Revoking the key stops the agent at once. Ask before every trade makes the agent name the token, contract, amount and price, then wait for your yes. Trades are real money, not a simulation.

Frequently asked questions

How do I add an MCP server to Claude Code?

Run claude mcp add with a name. For a remote server, use claude mcp add --transport http <name> <url>, and add --header for a bearer token. For a local server, add two dashes and the command that starts it. Then run claude mcp list to check it.

What is the difference between Claude Code and MCP?

Claude Code is Anthropic's command-line coding agent. MCP, the Model Context Protocol, is an open standard that lets an AI app call outside tools. Claude Code is the client, and each MCP server you add gives it new tools it can call during a session.

Where does Claude Code store MCP servers?

Local and user scope servers are stored in ~/.claude.json. Local entries sit under the current project path, and user entries load in all your projects. Project scope servers live in a .mcp.json file in the project root, which you can commit to share with your team.

What is the difference between local, project and user scope?

Local is the default and loads only in the current project, just for you. Project writes the server to .mcp.json so your team gets it too. User loads the server in all your projects. If the same name exists in more than one scope, local wins, then project, then user.

How do I keep an API key out of .mcp.json?

Use environment variable expansion. Write the header as Bearer ${MY_API_KEY} and set MY_API_KEY in your shell before you start Claude Code. You can also give a default with ${VAR:-default}. This lets you commit .mcp.json without committing the secret.

Why does my project MCP server say Pending approval?

Claude Code does not load servers from a project's .mcp.json until you trust that workspace. Open the project, approve the server when Claude Code asks, then check /mcp. This stops a cloned repo from starting servers you did not choose.

How do I fix a Claude Code MCP server that times out?

For slow startup, raise MCP_TIMEOUT, for example MCP_TIMEOUT=10000 claude. For a slow tool, set a timeout in milliseconds on that server, which overrides MCP_TOOL_TIMEOUT. If tool output is too large, raise MAX_MCP_OUTPUT_TOKENS above the 25,000 default.

Can Claude Code trade crypto through MCP?

Yes, if you connect a trading MCP server. With the Moby MCP, Claude Code can research Solana tokens and trade from a Moby Agent wallet inside limits you set in the Moby app. The agent cannot withdraw or send funds, and every trade is real money.