MCP Servers

MCP stands for Model Context Protocol — an open standard developed by Anthropic for connecting AI applications to external tools and services. An MCP server is a process (local or remote) that exposes a set of callable tools. Once registered with Claude Code, those tools are available in every session — Claude calls them the same way it calls its built-in tools (Read, Write, Bash, etc.).

What you can connect

Any service with an MCP server implementation can be connected: calendar, email, databases, project management, accounting, CRMs, communication platforms. The protocol is open — any developer can build a server for any service, and hundreds already exist.

Transport types

MCP servers communicate via one of three transports:

• stdio — local process; Claude Code launches the server as a child process and communicates via standard in/out. Most common for npm packages and local scripts.
• http — remote server; Claude Code sends HTTP requests to a URL. The preferred transport for hosted or shared services.
• sse — Server-Sent Events; an older transport now deprecated in favour of HTTP. Avoid for new servers.

Registration — four scopes

MCP servers can be registered at four levels. More specific scopes override broader ones.

Local / personal (default)

Registered in ~/.claude.json — available in every Claude Code session on this machine, regardless of workspace. Use for servers you always want available: calendar, email, filesystem.

{
  "mcpServers": {
    "gcal": {
      "command": "node",
      "args": ["/path/to/gcal-server/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "...",
        "GOOGLE_CLIENT_SECRET": "..."
      }
    }
  }
}

Project-scoped (team-shared)

Registered in .mcp.json at the workspace root — available only when Claude Code is opened in that directory. Commit this file to share configuration with teammates. Never put credentials here — use environment variables and document required keys in a README.

{
  "mcpServers": {
    "project-db": {
      "command": "npx",
      "args": ["-y", "@myorg/project-db-mcp"],
      "env": {
        "DB_URL": "${PROJECT_DB_URL}"
      }
    }
  }
}

Managed (organisation-wide)

Set by an administrator in a system-level config file (/Library/Application Support/ClaudeCode/managed-mcp.json on macOS). Managed servers are always present and cannot be overridden or removed by users. Used to enforce organisation-wide tool access policies on Teams and Enterprise plans.

Adding servers via CLI

# Add a local stdio server (npm package)
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

# Add a remote HTTP server
claude mcp add my-server --transport http https://my-server.example.com/mcp

# Add with environment variables
claude mcp add notion --transport stdio --env NOTION_API_TOKEN=ntn_xxx -- npx -y @notionhq/notion-mcp-server

# Add with an auth header (HTTP servers)
claude mcp add remote-api --transport http https://api.example.com/mcp   --header "Authorization: Bearer $MY_TOKEN"

# List all registered servers
claude mcp list

# Get details for a specific server
claude mcp get filesystem

# Remove a server
claude mcp remove filesystem

OAuth authentication

Some MCP servers (particularly hosted services) use OAuth 2.0 rather than API tokens. The flow:

1. Register the server with claude mcp add
2. In a Claude Code session, run /mcp to see the server status
3. Click the authentication link — Claude Code opens your browser to the provider's OAuth page
4. Authorise access — the token is stored securely and refreshed automatically

If your system blocks the default OAuth callback port, specify a fixed port: claude mcp add my-server --transport http ... --callback-port 9876

Verifying connection

# In a Claude Code session
/mcp                        ← lists all servers and their status
"What tools do you have?"   ← Claude lists available tools by server

A hammer icon (🔨) in the input area indicates MCP tools are active. If the icon is missing, the server isn't connected — check ~/Library/Logs/Claude/mcp.log on macOS for startup errors.

Security

MCP servers run with your local user permissions. A server can read files, make network calls, and execute commands — the same as any installed software. Only install servers from sources you trust. Review source code of community servers before adding credentials. Never commit API tokens to version-controlled config files — use environment variables. Treat MCP server installation with the same caution as installing any application.