Claude Code MCP setup: claude mcp add, .mcp.json, scopes and fixes

To add an MCP server to Claude Code, run claude mcp add in your terminal: claude mcp add --transport http <name> <url> for a hosted server, or claude mcp add <name> -- <command> for one that runs on your machine. Claude Code saves it to ~/.claude.json, or to .mcp.json when you share it with the project, and claude mcp list shows whether it connected. Inside a session, /mcp handles sign-in and status.

Every command below matches the Claude Code docs as of October 2026. If MCP itself is new to you, start with what an MCP server is.

Add a remote (HTTP) server

Most SaaS apps host their own server at a URL. Add it with the HTTP transport and a name you choose:

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

Run this in your shell, not inside a claude session. Until you sign in, claude mcp list shows the server as ! Needs authentication. Start claude, type /mcp, select the server and choose Authenticate: your browser opens the vendor's OAuth page, and Claude Code stores and refreshes the token from then on. claude mcp login sentry does the same from the shell.

Servers that take a fixed token instead of OAuth get it as a header:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

The older SSE transport still works with --transport sse, but it is deprecated. Prefer HTTP wherever the server supports it.

Add a local (stdio) server

A local server is a program Claude Code starts on your machine. Everything after -- is the command that starts it:

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

Pass API keys with --env (short form -e). Put another option between the last --env and the server name, or Claude Code reads the name as one more key-value pair:

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

The -- separator matters: without it, a server flag such as --port is parsed as a Claude Code option. The first claude mcp list after adding an npx server can show ✘ Failed to connect while the package downloads; give it a moment and run it again.

Pick a scope

Every server is saved at one of three scopes, chosen with --scope (short form -s):

Use user for servers you want everywhere, such as GitHub or Linear, project for servers the whole team needs in one repository, and local for trying something out. A scope is fixed when you add a server, so to move one, remove it and add it again. When the same name exists at several scopes, local wins over project and project over user.

The .mcp.json config file

The project config file is plain JSON that you can write by hand and commit:

{
  "mcpServers": {
    "linear": {
      "type": "http",
      "url": "https://mcp.linear.app/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "internal-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${INTERNAL_API_TOKEN}" }
    }
  }
}

The rules that trip people up:

• Claude Code expands ${VAR} and ${VAR:-default} in command, args, env, url and headers. Tokens stay in each person's environment and out of git.
• Give every URL entry a "type". An entry with a url and no type is treated as stdio and skipped.
• The file is read when a session starts, so restart after editing it.
• The first time someone opens the project, Claude Code asks them to approve its servers, so a cloned repository can't start processes without consent. claude mcp reset-project-choices clears earlier answers.
• Claude Code reads only ~/.claude.json and the project's .mcp.json. Paths such as ~/.claude/mcp.json are ignored.

You can also pass a whole entry from the shell with claude mcp add-json <name> '<json>'.

Manage your servers

Connectors you added on claude.ai also show up here when you sign in to Claude Code with that account. Start Claude Code with ENABLE_CLAUDEAI_MCP_SERVERS=false to leave them out for that shell.

Troubleshooting Claude Code MCP servers

Two settings help with heavy servers: MAX_MCP_OUTPUT_TOKENS raises the cap on a single tool result (25,000 tokens by default), and a "timeout" in milliseconds on a server's entry gives slow tools more time.

Scheduled and headless runs

claude -p and the Agent SDK can't complete an OAuth sign-in, so sign in once from an interactive session; the stored token is reused afterward. In claude -p, project servers from .mcp.json load without the approval prompt, which is one more reason to commit only servers you trust.

That is how the scheduled skills in the skills library run: cron starts claude -p "Run the weekly-seo-report skill", the skill reads the data through the MCP server, and the result lands on your Briefkin board as a card. For Claude Code on the web, commit .mcp.json to the repository and the cloud session loads it.

The same setup in Codex

Codex keeps MCP servers in ~/.codex/config.toml, or .codex/config.toml in a trusted project, and the CLI, the IDE extension and Codex in the ChatGPT desktop app share that config. From the terminal:

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add linear --url https://mcp.linear.app/mcp
codex mcp login linear
codex mcp list

Or write the entries yourself:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

Inside the Codex TUI, /mcp lists the active servers. startup_timeout_sec defaults to 10 seconds and tool_timeout_sec to 60.

The same setup in Cursor

Cursor reads .cursor/mcp.json in the project and ~/.cursor/mcp.json for every project. The shape matches Claude Code's mcpServers object, but environment variables are written ${env:NAME}:

{
  "mcpServers": {
    "linear": { "url": "https://mcp.linear.app/mcp" },
    "airtable": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "airtable-mcp-server"],
      "env": { "AIRTABLE_API_KEY": "${env:AIRTABLE_API_KEY}" }
    }
  }
}

Turn servers on and off under Customize in Cursor's sidebar, and open the Output panel's MCP Logs when one fails to start.