How to add a server in Claude Code

By mcp-guide · 0 stars

Prerequisites: Claude Code installed; the server URL, or the command that starts a local server.

1. Add the server. Remote HTTP:

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

With a token header instead of OAuth:

~~~bash
claude mcp add --transport http api https://api.example.com/mcp --header "Authorization: Bearer $TOKEN"
~~~

Local stdio (everything after `--` is the command):

~~~bash
claude mcp add --transport stdio --env AIRTABLE_API_KEY=xxx airtable -- npx -y airtable-mcp-server
~~~

2. Run `claude mcp list`. You should see the new server.
3. Start a session and run `/mcp`.
4. Sign in to the server from `/mcp` if it uses OAuth. You should see it listed as connected.

Add `--scope` to choose where it is saved:

| Scope | Applies to | Stored in | Shared |
|---|---|---|---|
| `local` (default) | This project, only you | `~/.claude.json` | No |
| `project` | This project, whole team | `.mcp.json` in repo root | Yes, via git |
| `user` | All your projects | `~/.claude.json` | No |

Keep secrets out of `.mcp.json` with `${VAR}` and `${VAR:-default}`:

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

Each teammate approves `.mcp.json` servers the first time.

### Manage

~~~bash
claude mcp get <name>
claude mcp remove <name>
claude mcp login <name>      # OAuth sign-in from the terminal
claude mcp logout <name>
claude mcp add-from-claude-desktop   # import (macOS and WSL)
~~~

### Settings

- `MCP_TIMEOUT`: startup timeout in ms.
- `MAX_MCP_OUTPUT_TOKENS`: default 25,000; warns above 10,000.
- Tool names are `mcp__<server>__<tool>`; permission rules use the same names.
- Admins: `allowedMcpServers` / `deniedMcpServers`, or a managed server list.
- Plugins can bundle servers.
- From the Claude API, the MCP connector lets a Messages API request call remote servers directly.

### Sources

- https://code.claude.com/docs/en/mcp
- https://platform.claude.com/docs/en/agents-and-tools/mcp-connector