Guides

Adding and using MCP servers in Claude Code

MCP (Model Context Protocol) servers give Claude Code extra tools: talking to Notion, querying a database, calling an internal API. You add them with claude mcp add, and where you add them decides who else on your team gets them for free.

Adding a server

Remote servers (HTTP is the current transport; SSE still works but is deprecated):

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

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Local servers that run as a subprocess use -- to separate Claude's own flags from the server's command line:

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

You can also register a server directly from JSON, which is handy for pasting a config someone else gives you:

claude mcp add-json weather-api \
  '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

Scopes

Scope	Flag	Stored in	Shared with team?
Local	default, or -s local	~/.claude.json	No
Project	-s project	.mcp.json in the repo root	Yes, via git
User	-s user	~/.claude.json	No, but works in every project

Local is the default and is private to you and the current project — good for a personal API key or an experimental server you're not ready to commit. Project scope writes to .mcp.json, which you commit so teammates get the same tools; Claude Code asks for approval the first time it loads a project-scoped server in an interactive session. User scope is private to you but follows you into every project, which suits a general-purpose utility server you always want available.

.mcp.json

Project-scoped servers live in a plain JSON file at the repository root:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    },
    "database-tools": {
      "command": "npx",
      "args": ["-y", "some-db-mcp-server"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

${VAR} and ${VAR:-default} expand from the environment at load time in command, args, env, url and headers, so you can commit the file without committing secrets. Don't put raw API keys directly in .mcp.json; reference an environment variable instead, and keep the actual value out of git the same way you'd handle any other secret — see the settings.json guide for the equivalent advice on env there.

Managing servers

claude mcp list          # every configured server, with connection status
claude mcp get notion    # full config for one server
claude mcp remove notion

claude mcp list shows a status next to each entry: connected, needs authentication, failed to connect, pending approval, or disabled for this project. Inside a session, run /mcp to see the same status, browse the tools each server exposes, authenticate a server that needs OAuth, and toggle servers on or off for the current project.

OAuth-based servers

Some remote servers (Sentry, HubSpot, and similar SaaS integrations) authenticate with OAuth instead of a static header:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
claude mcp login sentry          # or use /mcp inside a session
claude mcp login sentry --no-browser   # for SSH / headless sessions
claude mcp logout sentry         # clear stored credentials

Tokens are stored and refreshed automatically after the first login, so you only authenticate once per machine.

Troubleshooting

• Server doesn't show up: check the scope you added it with, and note that project scope needs a one-time approval in each new interactive session.
• Stdio server fails immediately: confirm the command runs on its own outside Claude Code, and that everything after -- is the server's own argv, not a Claude flag.
• Warnings in claude mcp list: usually a missing ${VAR}, hidden whitespace pasted into a URL or token, or the same server name registered in two scopes at once.

Once tools are loaded, the model still needs to be pointed at the right moment to use them; a hook can enforce that automatically, and the free hook builder is a quick way to write and test one without hand-rolling the matcher regex. For the surrounding .claude/settings.json that controls which servers are approved automatically, see the settings.json guide.