AX-Copilot/docs/claude-code-docs-main/en/guides/mcp-servers.md

Documentation Index

Fetch the complete documentation index at: https://vineetagarwal-code-claude-code.mintlify.app/llms.txt Use this file to discover all available pages before exploring further.

MCP servers

Extend Claude Code with Model Context Protocol servers to connect databases, APIs, and custom tools.

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.

Connect Claude to any service that exposes an MCP server: databases, APIs, file systems, and more. Save server configs per-project in `.mcp.json` or globally in your user settings. Turn individual servers on and off with `/mcp enable` and `/mcp disable` without editing config files. 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.

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

```json  theme={null}
{
  "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

For servers hosted as HTTP endpoints:

```json  theme={null}
{
  "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

For servers using the SSE transport:

```json  theme={null}
{
  "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:

Scope	Location	Use case
project	.mcp.json in the current directory (and parent directories up to root)	Team-shared server configs
user	~/.claude.json (global config)	Personal servers available everywhere
local	.claude/settings.local.json in the current project	Per-project personal overrides, not committed to VCS

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

In auto mode (`--allowedTools`), MCP tools can be pre-approved by including their full name (formatted as `mcp____`) 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.

```bash theme={null} claude mcp add --scope project filesystem -- npx -y @modelcontextprotocol/server-filesystem /home/user/projects ``` Run `/mcp` and confirm `filesystem` shows as **connected**. 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

{
  "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

* 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 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. 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`. On Windows, `npx` requires a `cmd /c` wrapper:

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

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.

Built with Mintlify.