MCP servers

Model Context Protocol (MCP) is an open standard that lets Claude Code connect to external data sources and services. When you add an MCP server, Claude gains access to new tools — for example, querying a database, reading Jira tickets, or interacting with a Slack workspace.

• Extend Claude's capabilities — Connect Claude to any service that exposes an MCP server: databases, APIs, file systems, and more.

  • Project or user scope — Save server configs per-project in .mcp.json or globally in your user settings.

  • Enable and disable at runtime — Turn individual servers on and off with /mcp enable and /mcp disable without editing config files.

  • Permission gating — Claude Code prompts before calling any MCP tool, giving you control over what actions are taken.

Adding a server

The primary way to add an MCP server is via the claude mcp add CLI command, or by editing a config file directly.

Via the CLI

Run /mcp to open the MCP management panel where you can enable, disable, and reconnect servers.

To add a server from the command line using the claude CLI:

claude mcp add <name> -- <command> [args...]

For example, to add the official filesystem MCP server:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp

Specify the scope with --scope:

# Save to .mcp.json in the current directory (shared with your team)
claude mcp add --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp

# Save to your user config (available in all projects)
claude mcp add --scope user my-db -- npx -y @my-org/mcp-server-postgres

Via the --mcp-config flag

Pass a JSON config file when starting Claude Code:

claude --mcp-config ./my-mcp-config.json

This is useful for CI environments or when you want a self-contained configuration that is not persisted to any settings file.

Config file format

MCP server configurations use JSON with a top-level mcpServers key. Each server entry has a name and a configuration object.

Stdio (local process)

Most MCP servers run as a local subprocess communicating over stdin/stdout:

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```

Fields:

* `command` — the executable to run (required)
* `args` — array of command-line arguments
* `env` — environment variables to pass to the process

HTTP (remote server)

For servers hosted as HTTP endpoints:

```json
{
  "mcpServers": {
    "my-api": {
      "type": "http",
      "url": "https://mcp.example.com/v1",
      "headers": {
        "Authorization": "Bearer $MY_API_TOKEN"
      }
    }
  }
}
```

Fields:

* `type` — set to `"http"`
* `url` — the server URL (required)
* `headers` — HTTP headers; values support `$VAR` environment variable expansion

SSE (server-sent events)

For servers using the SSE transport:

```json
{
  "mcpServers": {
    "events-server": {
      "type": "sse",
      "url": "https://mcp.example.com/sse"
    }
  }
}
```

Server names may only contain letters, numbers, hyphens, and underscores.

Environment variable expansion

Values in command, args, url, and headers support $VAR and ${VAR} syntax. Variables are expanded at startup from the shell environment. If a referenced variable is missing, Claude Code logs a warning but still attempts to connect.

Configuration scopes

MCP configs are stored in different places depending on scope:

When the same server name appears in multiple scopes, local takes precedence over project, which takes precedence over user.

Managing servers

Enable and disable

/mcp enable <server-name>
/mcp disable <server-name>
/mcp enable all
/mcp disable all

Disabled servers remain in the config but are not connected at startup. This is useful for servers you want to keep configured but not always running.

Reconnect a server

If a server fails to connect or you need to force a reconnection:

/mcp reconnect <server-name>

View server status

Run /mcp to see a list of all configured servers and their current connection status:

• connected — server is running and ready to use
• pending — server is starting up
• failed — server could not connect (check the error message)
• needs-auth — server requires OAuth authorization
• disabled — server is configured but turned off

Approving MCP tool calls

Claude Code displays a permission prompt before calling any MCP tool. The prompt shows the tool name and its input arguments, so you can review what Claude is about to do before it executes.

You can:

• Allow once — approve this specific call
• Allow always — approve all calls to this tool in this session
• Deny — block the call; Claude receives an error and can try a different approach

Note: In auto mode (--allowedTools), MCP tools can be pre-approved by including their full name (formatted as mcp__<server-name>__<tool-name>) in the allowed tools list.

Example: filesystem server

The official filesystem MCP server gives Claude the ability to read and write files in directories you specify.

1. Add the server

    claude mcp add --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem /home/user/projects
    ```


  ### 2. Verify the connection

Run `/mcp` and confirm `filesystem` shows as **connected**.


  ### 3. Use it

Claude can now read and write files in `/home/user/projects` using the `mcp__filesystem__read_file` and `mcp__filesystem__write_file` tools.

## Example: database server

```json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "$DATABASE_URL"
      }
    }
  }
}

Set DATABASE_URL in your environment before starting Claude Code, and the MCP server will receive it automatically.

Official MCP registry

Anthropic and the community maintain an MCP server registry at modelcontextprotocol.io. Browse available servers for databases, productivity tools, cloud providers, and more.

Troubleshooting

Server shows as 'failed'

• Check that the command exists and is executable: which npx

  • Run the command manually in your terminal to see if it starts without errors
  • Check that required environment variables (like API keys) are set
  • Run claude --debug to see detailed connection logs

  MCP tools not appearing

A server that is connected but unauthenticated will not expose any tools. Look for a needs-auth status in /mcp and follow the OAuth flow to authorize.

Environment variable not expanded

Claude Code expands variables from the process environment at startup. If a variable is not set in your shell profile, it will not be available. Verify with echo $YOUR_VAR in the same terminal before starting claude.

Windows: npx fails to start

On Windows, npx requires a cmd /c wrapper:

```json
{
  "mcpServers": {
    "my-server": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@my-org/mcp-server"]
    }
  }
}
```

Server works locally but not in CI

Use the --mcp-config flag to pass a config file explicitly, and ensure all referenced environment variables are set in the CI environment. For stdio servers, make sure the command (e.g., npx, node) is available in the CI PATH.