How to Add an MCP Server to Claude Code

Claude Code connects to MCP servers with one terminal command. You run claude mcp add, give the server a name, and point it at either a URL (a hosted server) or a command (a server that runs on your machine). The rest of this guide covers both, plus scopes, sign-in, secrets and the errors you're most likely to hit.

Every server in our MCP server directory with verified connection details has a ready-made Claude Code command on its page, so if you already know which server you want, start there.

Before you start

You need Claude Code installed and signed in, and a terminal open in the project you want the server available in. Run claude mcp add from your normal shell, not inside a running claude session.

For local servers you also need whatever runtime the server is launched with. Most use npx (Node.js 18 or later), some use uvx (Python's uv) or docker. The server's page in the directory tells you which.

Add a hosted server

A hosted server is one the vendor runs for you. You connect to its URL over HTTP and there's nothing to install. This is the simplest option and the one most vendors now recommend.

claude mcp add --transport http notion https://mcp.notion.com/mcp

The parts are: --transport http because the server lives at a URL, notion as the name you'll see in Claude's output (call it anything), and the endpoint itself.

Most hosted servers use OAuth, so the next step is signing in. Start Claude Code, run /mcp, pick the server and choose Authenticate. Your browser opens the vendor's sign-in page, you approve access, and the server shows as connected.

Some hosted servers take an API key in a header instead of OAuth. Pass it when you add the server:

claude mcp add --transport http context7 https://mcp.context7.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

A few vendors still only document an SSE endpoint (the URL usually ends in /sse). Use --transport sse for those. SSE is deprecated in the MCP spec but Claude Code still supports it.

Add a local server

A local server is a program Claude Code starts on your machine. Use one when the tool needs local access, like a browser, your files or a database on your network, or when the vendor doesn't host a server.

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

Everything after -- is the command Claude Code runs. Options for Claude Code itself (--transport, --env, --scope) go before the server name, and the server's own arguments go after --. Getting that order wrong is the most common reason a local server won't start.

If the server needs a key, pass it as an environment variable:

claude mcp add --env BRAVE_API_KEY=YOUR_API_KEY brave-search \
  -- npx -y @brave/brave-search-mcp-server --transport stdio

Choose a scope

By default a server is added at local scope: only you, only this project. Two other scopes are worth knowing:

Add --scope user for tools you want everywhere (search, docs, your issue tracker). Use --scope project for servers the whole team should share, then commit .mcp.json. Teammates are asked to approve a project server the first time they open the repo, so a cloned repository can't quietly start processes on their machine.

You can also write .mcp.json by hand. It uses the same format as the other scopes:

{
  "mcpServers": {
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Don't commit API keys in .mcp.json. Share servers that use OAuth, where each person signs in with their own account, or have teammates set keys at local scope.

Check it's working

claude mcp list

Connected means you're done. Needs authentication means run /mcp and sign in. Failed to connect usually means a wrong URL or a local command that errors. Run claude mcp get <name> to see the exact error and the command Claude Code is running.

Inside a session, /mcp shows every server, its status and its tools, and lets you reconnect or re-authenticate without leaving.

Common problems

The server was added but doesn't show up. Local-scope servers belong to the directory you added them from. Re-add it from the right project, or use --scope user.

A local server fails on first run. npx may still be downloading the package. Wait and check again, or raise the startup timeout with MCP_TIMEOUT=60000 claude.

It connects but no tools appear. The server usually needs an environment variable it didn't get. Check the server's page for what it requires and re-add it with --env.

You already use servers in Claude Desktop. On macOS and WSL, claude mcp add-from-claude-desktop copies them across.

Keep it lean

Every connected server loads its tool list into each session, which uses context. Connect the servers you actually use, remove the rest with claude mcp remove <name>, and prefer a vendor's hosted server over a community one where both exist. Our guide to how MCP clients and servers fit together explains why that matters.

Setting up MCP for a team rather than just yourself? That's the point where permissions, shared config and governance start to matter, and it's the work Crox does in a Build engagement.