Skip to main content

How to Connect MCP Servers to Claude Code

Short answer

Run claude mcp add with a name you choose. For a local server, put the command that starts it after --, for example claude mcp add memory -- npx -y @modelcontextprotocol/server-memory. For a remote server, add --transport http and the URL, for example claude mcp add --transport http sentry https://mcp.sentry.dev/mcp. Claude Code saves the server in ~/.claude.json for the current project by default. Add --scope project to save it in a .mcp.json file in the project root instead, so your team gets it too.

Tested withClaude Code 2.1.304Checked 20 Oct 2026

By Tony LewisHow we test these guides

What you'll have at the end​

A local memory server registered with Claude Code, connected and listed as a stdio server. This is the output we got from claude mcp get memory after adding it:

memory:
  Scope: Local config (private to you in this project)
  Status: ✔ Connected
  Type: stdio
  Command: npx
  Args: -y @modelcontextprotocol/server-memory
  Environment:

To remove this server, run: claude mcp remove memory -s local

Before you start

  • Claude Code installed, so that claude runs in your terminal.
  • Node.js with npx, for the local server example. The remote example needs nothing extra, but you need an account with the service if it asks you to sign in.
  • A project folder to run the commands in. Local and project scopes depend on the folder you're in when you run the command.

1. Add a local (stdio) server​

A local server runs on your computer. Claude Code starts it as a child process and talks to it over standard input and output. You describe it with the command that starts it:

claude mcp add memory -- npx -y @modelcontextprotocol/server-memory

The name memory is how you'll refer to the server in later commands. The -- separates Claude Code's own options from the command that runs the server. Everything after -- goes to the server unchanged, so flags like -y and --port 8080 reach the command and not Claude Code. To set an environment variable, add -e or --env before the server name, for example -e API_KEY=your-key. If --env sits directly before the name, Claude Code reads the name as another variable, so put another option such as --transport stdio between them.

Claude Code prints one line when the server is saved:

Added stdio MCP server memory with command: npx -y @modelcontextprotocol/server-memory to local config

2. Add a remote (HTTP) server​

A remote server runs somewhere else, and you give Claude Code its URL. Use the http transport:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

If the service gives you a token and no OAuth sign-in, pass it as a header. Put --header after the URL, because it accepts several values and would otherwise read the server name as one of them:

claude mcp add --transport http my-api https://api.example.com/mcp --header "Authorization: Bearer YOUR_TOKEN"

This command saves the token in ~/.claude.json, which isn't in your repository, so keep it in local or user scope rather than project scope. Some servers still offer only the older SSE transport. Use --transport sse for those. Claude Code's docs describe SSE as deprecated, so use HTTP whenever the server offers it.

3. Choose a scope​

The scope decides which projects load the server and whether your team gets it. Claude Code has three:

ScopeFlagSaved inWho gets it
Local (default)--scope local or none~/.claude.json, under the current projectOnly you, and only in this project
Project--scope project.mcp.json in the project rootAnyone who clones the repository
User--scope user~/.claude.jsonYou, in every project

If the same server name exists in more than one scope, the local one wins, then project, then user. Claude Code uses that one entry and doesn't merge fields across scopes.

To share a server with your team, add it to the project scope:

claude mcp add --transport http --scope project sentry https://mcp.sentry.dev/mcp

Claude Code writes this to .mcp.json:

remote.mcp.json
{
  "mcpServers": {
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

A local server in project scope looks like this:

stdio.mcp.json
{
  "mcpServers": {
    "memory": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {}
    }
  }
}

Commit .mcp.json to version control. Before Claude Code uses a project server in an interactive session, it asks you to approve it. Until you approve it, claude mcp list shows the server as ⏸ Pending approval. Run claude in the project to review the prompt. To reset every approve and reject choice for the project, run claude mcp reset-project-choices.

The config files live in these places:

OSLocal and user scopeProject scope
macOS and Linux~/.claude.json.mcp.json in the project root
Windows%USERPROFILE%\.claude.json.mcp.json in the project root

You don't need to edit ~/.claude.json by hand. The claude mcp commands write to it for you. We ran the commands on macOS.

4. Sign in with OAuth​

Many remote servers need you to sign in with your account. When one does, Claude Code marks it as needing authentication. Sign in from inside a session:

  1. Start Claude Code with claude in your project.
  2. Type /mcp.
  3. Select the server and follow the browser login.

Tokens are stored for you and refreshed automatically. To revoke Claude Code's access, open /mcp, select the server, and choose Clear authentication.

You can also sign in from your shell, without opening /mcp:

claude mcp login sentry

If no browser is available, such as on a remote machine over SSH, the command prints the authorization URL. Open it on a machine with a browser, then paste the full redirect URL from the address bar back into the terminal. Use claude mcp login sentry --no-browser to force that flow. To clear stored credentials, run claude mcp logout sentry.

Some servers need a fixed callback port that you registered with the service. Pass it with --callback-port:

claude mcp add --transport http --callback-port 8080 my-server https://mcp.example.com/mcp
note

claude mcp login and claude mcp logout are in Claude Code 2.1.304, the version we tested. Older versions, such as 2.1.178, don't have them, so use /mcp there or update Claude Code.

5. Check the connection​

Run claude mcp list to see every server and its status:

StatusMeaning
✔ ConnectedClaude Code connected to the server.
! Needs authenticationThe server returned 401 or 403. Sign in from /mcp.
✘ Failed to connectClaude Code couldn't connect. claude mcp get <name> shows the error.
⏸ Pending approvalA project server you haven't approved yet.

For one server, run claude mcp get <name>. The output at the top of this guide is the result for a connected server. Inside a session, /mcp also shows the number of tools each connected server offers.

6. List, update, and remove​

To remove a server, name it and, if needed, its scope:

claude mcp remove sentry
claude mcp remove sentry --scope project

When you remove a remote server, Claude Code also deletes the OAuth tokens and client registration it stored for that server. To change a server's URL, remove it and add it again with the new URL.

If you already have servers in Claude Desktop, claude mcp add-from-claude-desktop lets you import them. The import works on macOS and in Windows Subsystem for Linux (WSL). If you have a JSON config from another app, claude mcp add-json takes the object and adds it:

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

Common problems​

MCP server sentry already exists in local config You already have a server with that name in the same scope. Pick another name, or remove the old one first with claude mcp remove sentry.

Skipped — MCP server "bad" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry A .mcp.json entry has a url but no type. Claude Code reads an entry without a type as a stdio server, so it skips it. Add "type": "http" next to the url.

⏸ Pending approval You haven't approved a project server yet. Run claude in the project and approve it. If you rejected it by mistake, run claude mcp reset-project-choices.

! Needs authentication The server rejected the request with 401 or 403. Sign in from /mcp, or run claude mcp login <name> in your shell.

✘ Failed to connect Run claude mcp get <name>. The Issue: line gives the reason. A server whose hostname doesn't resolve shows a line like this:

  Status: ✘ Failed to connect
  Issue: ENOTFOUND: getaddrinfo ENOTFOUND api.example.com

For an HTTP server, the Issue: line shows the HTTP status or error code the server returned. If you set your own Authorization header and the server rejects it, Claude Code reports the failure instead of starting OAuth. Check the token in the header.

No MCP server named "sentry" in .mcp.json The server is in a different scope. Run claude mcp list to see where it lives, then pass the matching --scope.

Token headers that read as empty A ${VAR} reference in a remote server's url or headers can expand to an empty value. Claude Code does this on purpose for some credential variables, such as ANTHROPIC_AUTH_TOKEN, so a project file can't send them to a server. The server then gets Bearer with no token. Put the token in a variable with a name of your own, and check the docs on expanding variables.

FAQ​

Where does claude mcp add save a server?

By default it saves the server in ~/.claude.json for the current project, so only you see it, and only in that project. Use --scope user to make it available in every project, or --scope project to save it in .mcp.json so your team can use it too.

How do I see which MCP servers Claude Code is using?

Run claude mcp list in your terminal to see every server and whether it is connected. Inside a Claude Code session, type /mcp to see the same servers with their tool counts and sign-in status.

How do I remove an MCP server from Claude Code?

Run claude mcp remove followed by the server name, for example claude mcp remove sentry. If the name exists in more than one scope, add --scope with the scope you want to remove from.

Why does a server in my project say Pending approval?

Claude Code asks you to approve each server in a project .mcp.json file before it connects, for safety. Start claude in that project, review the prompt and approve the server. Until you do, the server stays disconnected.