How-to guidesOctober 23, 20265 min read

How to add an MCP server to Claude Code

claude code mcpadd mcp serverremote mcp servermcp jsonclaude codemcp

An MCP server gives Claude Code new tools. For example, a GitHub server lets it read issues, a Playwright server lets it open a browser, and a hosting server lets it put your app online.

You add a server with one command:

bash

claude mcp add --transport http my-server https://example.com/mcp

That's the short version. Below is the rest: local and remote servers, where the settings are saved, how to log in, and what to do when a server doesn't connect.

Local or remote?

There are two kinds of MCP servers.

Local (stdio). The server is a program on your computer. Claude Code starts it for you, usually with npx or uvx.
Remote (HTTP). The server runs somewhere on the internet. Claude Code connects to its address. Nothing to install.

The README of the server tells you which kind it is. If it gives you a URL, it's remote. If it gives you a command like npx something, it's local.

Add a remote MCP server

Use --transport http, a name you choose, and the server's URL:

bash

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

Most remote servers need you to log in. There are two ways.

Log in with the browser (OAuth). Open Claude Code, type /mcp, pick the server and choose Authenticate. A browser page opens, you log in and allow access. You can also do it from the terminal:

bash

claude mcp login sentry

Use a token. Some servers give you an API key instead. Send it in a header:

bash

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

Add a local MCP server

Put -- before the command that starts the server. Everything after -- is the command:

bash

claude mcp add playwright -- npx @playwright/mcp@latest

If the server needs an API key, pass it with -e:

bash

claude mcp add my-server -e API_KEY=YOUR_KEY -- npx my-mcp-server

You need Node.js for npx servers and Python with uv for uvx servers.

Where the server is saved: scopes

By default a server works only in the folder where you added it. Use --scope to change that:

Scope	Where it works	Where it's saved
`local` (default)	Only in this folder, only for you	Your Claude Code settings
`user`	In every folder on your computer	Your Claude Code settings
`project`	For everyone who works on this repository	`.mcp.json` in the project root

Want a server everywhere? Add --scope user:

bash

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

Share servers with your team: .mcp.json

With --scope project, Claude Code writes the server into .mcp.json. You commit this file, and your team gets the same servers. It looks like this:

json

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MY_SERVER_TOKEN}"
      }
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {}
    }
  }
}

Don't put real tokens in this file, because it goes to git. Write ${MY_SERVER_TOKEN} instead, and each person sets the variable in their own terminal. Claude Code puts the value in when it connects.

The first time someone opens the project, Claude Code asks them to approve the servers from .mcp.json. That's normal: a file from git shouldn't run programs on your computer without asking.

Check that it works

In the terminal:

bash

claude mcp list

You see every server and whether it is connected. For one server:

bash

claude mcp get sentry

Inside Claude Code, type /mcp. It shows the same list, and you can log in, reconnect or turn a server off there.

Then just ask Claude to use it: "List my open Sentry issues". If the server works, Claude calls its tools.

Remove a server

bash

claude mcp remove sentry

Claude Code finds it in any scope. If you have servers with the same name in two scopes, say which one: claude mcp remove --scope user sentry.

When the server doesn't connect

"Failed to connect" for a remote server. Check the URL. Many servers end with /mcp. Open /mcp in Claude Code and try Authenticate again.
"Needs authentication". You haven't logged in yet, or the login expired. Run /mcp or claude mcp login <name>.
401 or 403 with a token. The header must be exactly Authorization: Bearer <token>, with one space after Bearer. Check that the token is not expired.
A local server fails to start. Run its command by hand in the terminal, for example npx @playwright/mcp@latest. You will see the real error, often a missing Node.js or Python.
The server is connected, but Claude doesn't use it. Name it in your request: "use the Playwright MCP to open the page". Claude picks tools by their names and descriptions.
A server from .mcp.json is "pending approval". Approve it in /mcp. If you said no by mistake, run claude mcp reset-project-choices.

Example: a remote server that deploys your code

Here is a real remote MCP server: vbtnl. It gives Claude Code tools to create a project on a server, write files there, run them and publish the app to a public address.

bash

claude mcp add --scope user --transport http vbtnl https://api.vbtnl.com/mcp

Then /mcp, pick vbtnl and log in. Now you can ask:

Code

Make a landing page with a waitlist and put it online on vbtnl.

Claude writes the code on the server, starts it and replies with a link. For a full example, see Deploy a Telegram bot for free with Claude Code. Setup for other apps is in the docs.

Which MCP servers to add

Start with the ones that match your daily work. Popular choices for Claude Code:

GitHub for issues and pull requests.
Playwright to open pages in a real browser and test them.
Figma to read designs and turn them into code.
A database server (Postgres, Supabase) to look at your data.
A hosting server like vbtnl to put what Claude builds online.

Don't add twenty servers at once. Every server adds tools, and with too many tools Claude picks the wrong one more often. Add what you use, remove what you don't.

Questions

What is the difference between Claude Code and Claude Desktop for MCP?

Claude Code adds servers with claude mcp add or .mcp.json. Claude Desktop and claude.ai add remote servers as custom connectors in Settings. On a Mac you can copy servers from Claude Desktop with claude mcp add-from-claude-desktop.

Can I add a server from a JSON config?

Yes. claude mcp add-json my-server '{"type":"http","url":"https://example.com/mcp"}' takes the same JSON as .mcp.json.

Do MCP servers see my code?

A server sees only what Claude sends to it in a tool call. Still, a local server is a program on your computer, so add only servers you trust.

Does the same work in Codex?

Almost. Codex has its own command: codex mcp add. See Connect Codex.