> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/jackdog668/claude-code/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP servers

> Connect Claude Code to external tools and services using the Model Context Protocol.

MCP (Model Context Protocol) is an open standard that lets Claude Code connect to external servers that expose tools, resources, and prompts. When an MCP server is connected, Claude can call its tools the same way it calls built-in tools like Bash or file operations.

## Adding an MCP server

Use `claude mcp add` to register a server. The command syntax depends on the transport type.

<Tabs>
  <Tab title="Stdio (default)">
    Stdio servers run as a local subprocess. The command and any arguments are passed directly.

    ```bash theme={null}
    claude mcp add <name> <command> [args...]
    ```

    **Examples:**

    ```bash theme={null}
    # Add a server that runs via npx
    claude mcp add my-server -- npx my-mcp-server

    # Add a server with subprocess flags
    claude mcp add my-server -- my-command --some-flag arg1

    # Add a server with environment variables
    claude mcp add -e API_KEY=xxx my-server -- npx my-mcp-server
    ```
  </Tab>

  <Tab title="HTTP">
    HTTP servers are remote endpoints that use the HTTP transport.

    ```bash theme={null}
    claude mcp add --transport http <name> <url>
    ```

    **Examples:**

    ```bash theme={null}
    # Add an HTTP server
    claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

    # Add an HTTP server with an Authorization header
    claude mcp add --transport http corridor https://app.corridor.dev/api/mcp \
      --header "Authorization: Bearer <token>"
    ```
  </Tab>

  <Tab title="SSE">
    SSE (Server-Sent Events) servers use a persistent HTTP connection.

    ```bash theme={null}
    claude mcp add --transport sse <name> <url>
    ```

    **Example:**

    ```bash theme={null}
    claude mcp add --transport sse my-sse-server https://example.com/sse
    ```
  </Tab>
</Tabs>

<Warning>
  If you pass a URL-shaped string without `--transport`, Claude Code will warn you that it is treating it as a stdio command. Always specify `--transport http` or `--transport sse` for remote servers.
</Warning>

## Scopes

Every MCP server is stored in one of three user-controlled scopes. Use `-s` or `--scope` to choose:

| Scope     | Flag                 | Where it's stored                              | Who it applies to                   |
| --------- | -------------------- | ---------------------------------------------- | ----------------------------------- |
| `local`   | `-s local` (default) | Global Claude config, keyed to current project | You, in this project only           |
| `project` | `-s project`         | `.mcp.json` in the project root                | Everyone who checks out the project |
| `user`    | `-s user`            | Global Claude config                           | You, in all your projects           |

```bash theme={null}
# Add for all your projects
claude mcp add -s user my-server -- npx my-mcp-server

# Add to the project's .mcp.json (commit this file to share with your team)
claude mcp add -s project my-server -- npx my-mcp-server
```

<Tip>
  Commit `.mcp.json` to version control to share a consistent set of MCP servers with your whole team.
</Tip>

## Listing and removing servers

```bash theme={null}
# List all configured servers and their status
claude mcp list

# Remove a server by name
claude mcp remove <name>
```

## The .mcp.json config file

When you use `--scope project`, Claude Code writes to a `.mcp.json` file in the current working directory. You can also create or edit this file directly.

```json theme={null}
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["my-mcp-server"],
      "env": {
        "API_KEY": "your-key-here"
      }
    },
    "remote-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}
```

The `type` field is optional for stdio servers (it defaults to `"stdio"`). For remote servers you must set `"type": "sse"` or `"type": "http"`.

## Environment variable expansion

Claude Code expands environment variables in MCP server configs at connection time. This applies to `command`, `args`, `env` values, and `url`/`headers` fields for remote servers.

```json theme={null}
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["my-mcp-server"],
      "env": {
        "API_KEY": "$MY_API_KEY"
      }
    }
  }
}
```

## Transport types

The source defines the following transport types for MCP server configs:

| Type    | Description                                                                                             |
| ------- | ------------------------------------------------------------------------------------------------------- |
| `stdio` | Launches a local subprocess and communicates over stdin/stdout. Default when no `--transport` is given. |
| `sse`   | Connects to a remote server using Server-Sent Events over HTTP.                                         |
| `http`  | Connects to a remote server using streamable HTTP.                                                      |

<Note>
  The `ws` (WebSocket) transport type exists in the codebase but is not exposed via `claude mcp add`. The `sse-ide`, `ws-ide`, and `sdk` types are internal and used by IDE integrations.
</Note>

## Authentication for remote servers

For SSE and HTTP servers that require OAuth, pass the OAuth client ID and optionally a client secret:

```bash theme={null}
# Add with OAuth client ID
claude mcp add --transport http my-server https://example.com/mcp \
  --client-id <clientId>

# Prompt for client secret (or set MCP_CLIENT_SECRET env var)
claude mcp add --transport http my-server https://example.com/mcp \
  --client-id <clientId> \
  --client-secret

# Fix the OAuth callback port (for pre-registered redirect URIs)
claude mcp add --transport http my-server https://example.com/mcp \
  --client-id <clientId> \
  --callback-port 8080
```

<Note>
  `--client-id`, `--client-secret`, and `--callback-port` are only valid for `sse` and `http` transports. They are ignored for stdio servers.
</Note>

## Enabling and disabling servers

You can enable or disable MCP servers without removing them:

```bash theme={null}
# Disable a specific server
/mcp disable <name>

# Enable a specific server
/mcp enable <name>

# Disable all servers
/mcp disable

# Enable all servers
/mcp enable
```

## Reconnecting a server

If a server connection drops, you can reconnect it from within a session:

```bash theme={null}
/mcp reconnect <name>
```

## Enterprise policy settings

Administrators can control which MCP servers are available using policy configuration. Two lists are supported:

* **`allowedMcpServers`** — an allowlist. When set, only listed servers are permitted. An empty list blocks all servers.
* **`deniedMcpServers`** — a denylist. Listed servers are always blocked, even if they appear in the allowlist.

Entries can match by server name, by the command array (stdio servers), or by URL pattern with `*` wildcards (remote servers).

The enterprise-managed MCP config file is stored at the managed path as `managed-mcp.json`. When this file exists, it takes exclusive control of MCP configuration and users cannot add servers manually.

## Using MCP tools in a session

Once a server is connected, its tools appear in the tool list and Claude can call them automatically. Tools from MCP servers are prefixed with the server name (e.g., `mcp__myserver__toolname`).

Connected servers are shown with a status indicator. If a server has `needs-auth` status, you will be prompted to complete authentication before its tools are available.