Claude Code MCP: how to add servers and where the config lives

How to add an MCP server to Claude Code

1. Pick the transport

   Use HTTP for remote, cloud-hosted servers; it's the recommended transport, and Claude Code falls back to the deprecated SSE transport when a server only offers that. Use stdio for servers that run as a local process. For stdio, everything after -- is passed to the server untouched.

   # Remote HTTP server (recommended for cloud services)
   claude mcp add --transport http notion https://mcp.notion.com/mcp
   
   # With a bearer token
   claude mcp add --transport http secure-api https://api.example.com/mcp \
     --header "Authorization: Bearer your-token"
   
   # Local stdio server: everything after -- is the server's own command
   claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
     -- npx -y airtable-mcp-server

2. Choose a scope

   Without --scope, a server is local: only you, only this project. Add --scope project to write it to .mcp.json for the team, or --scope user for all your projects. See the table below.

3. Sign in if the server needs it

   Many remote servers use OAuth. Run /mcp inside Claude Code and choose the server to authenticate, or claude mcp login <name> in your shell. Headless -p runs can't open the sign-in flow, so sign in interactively first.

4. Check it connected

   Run /mcp to see each server's status and tools, and claude mcp list in your shell. Then ask Claude to use the tool by name.

5. Manage your servers

   List, inspect, remove or import servers from the command line. Disable one you rarely use from /mcp instead of removing it.

   claude mcp list            # every configured server
   claude mcp get notion      # one server's details
   claude mcp remove notion   # remove it (run claude mcp logout notion first to revoke tokens)
   claude mcp add-from-claude-desktop   # import from Claude Desktop (macOS, WSL)

Source: Claude Code docs, Connect Claude Code to tools via MCP

MCP scopes and config file locations

This is where Claude Code keeps MCP configuration. Note that MCP's "local" scope lives in ~/.claude.json, not in .claude/settings.local.json.

Share servers with .mcp.json

.mcp.json lets the whole team use the same servers. Keep secrets out of it with environment variables: ${VAR} expands to the variable's value, and ${VAR:-default} falls back to a default when it's unset. Expansion works in command, args, env, url and headers.

1. Reference variables instead of secrets

   Claude Code asks each person to approve project servers from .mcp.json the first time; claude mcp reset-project-choices resets those answers. A JSON entry with a url must also have a type, such as http.

   {
     "mcpServers": {
       "api-server": {
         "type": "http",
         "url": "${API_BASE_URL:-https://api.example.com}/mcp",
         "headers": {
           "Authorization": "Bearer ${API_KEY}"
         }
       }
     }
   }

Precedence, connectors and other details

• When the same server is defined twice, Claude Code connects once, using the first of: local, project, user, plugin, claude.ai connector. Entries aren't merged; an organization's managed servers outrank all of them.
• If you sign in to Claude Code with a claude.ai account, connectors you added in claude.ai show up automatically.
• Claude Code can be an MCP server itself: claude mcp serve exposes its tools to another client, such as Claude Desktop.
• Servers can also offer prompts that appear as slash commands; see Claude Code slash commands.
• Removing a remote server deletes the tokens Claude Code stored but doesn't revoke them; run claude mcp logout <name> first for that.

MCP and token usage

Tool definitions are deferred by default: only tool names and server instructions sit in context until Claude uses a tool, so a long list of servers costs less than it used to. Each server still adds something, so disable the ones you don't use in /mcp, and prefer a CLI such as gh, aws or gcloud when one exists, since it adds no tool listing at all. More in how to reduce Claude Code token usage.

Troubleshooting: when a server won't connect

• Shows as needing authentication: open /mcp and choose Re-authenticate, or run claude mcp login <name>.
• "has a url but no type": add "type": "http" (or sse or ws) to the JSON entry; without a type Claude Code treats it as stdio.
• A stdio server's flags were swallowed: put -- before the server's command so Claude Code doesn't parse them as its own.
• Missing-variable warning in claude mcp list: set the variable or give it a :-default.
• A project server never loads in claude -p: there's no approval prompt headlessly, so check your settings, or pass servers explicitly with --mcp-config and --strict-mcp-config.
• Server names added with claude mcp may only contain letters, numbers, hyphens and underscores.

Give your AI employees the same tools you use

MCP is how Claude Code reaches your issue tracker, database or analytics. Crewmark turns a Claude Code, Codex, DeepSeek Harness or OpenCode session into an AI employee with a role, a goal and working hours, woken on a heartbeat to take the next issue from a board, with your project's MCP servers available.

1. Commit .mcp.json

   Project-scoped servers load in the employee's session like in yours; sign it in once interactively for servers that need OAuth.

2. Let the heartbeat start the work

   During working hours the employee wakes every 15, 30 or 60 minutes in the same conversation; see how to make Claude Code proactive.

3. Give each role only what it needs

   An SEO employee gets Search Console; a programmer gets GitHub and Sentry. Read what an AI employee is.

Claude Code MCP FAQ