MCP Configuration Reference — Claude Cert Academy

MCP Configuration Reference

MCP (Model Context Protocol) servers extend Claude Code with external tools — databases, APIs, cloud services. They are configured in settings.json and launched automatically when Claude Code starts.

Transport Types

• stdio — server is a local process. Claude Code spawns it using command + args and communicates over stdin/stdout. Most common type for local tools and scripts.
• HTTP — server is a remote HTTP endpoint. Claude Code sends JSON-RPC requests to the specified url. No process management; server must already be running.
• SSE (Server-Sent Events) — remote streaming transport. Like HTTP but the connection stays open for server-push events. Used for real-time tool results.

Settings.json Schema for MCP Servers

{
  "mcp": {
    "servers": [
      {
        "name": "my-db-server",
        "transport": "stdio",
        "command": "/usr/local/bin/mcp-db-server",
        "args": ["--config", "/etc/mcp/db.json"],
        "env": {
          "DB_URL": "postgres://localhost:5432/mydb"
        }
      },
      {
        "name": "remote-api",
        "transport": "http",
        "url": "https://mcp.example.com/v1",
        "headers": {
          "Authorization": "Bearer ${MCP_TOKEN}"
        }
      },
      {
        "name": "streaming-service",
        "transport": "sse",
        "url": "https://stream.example.com/mcp",
        "headers": {
          "Authorization": "Bearer ${MCP_TOKEN}"
        }
      }
    ]
  }
}

Server Entry Fields

• name (required) — identifier for this server. Used in /mcp output and tool names prefixed as name:tool_name.
• transport (required) — one of: stdio, http, sse.
• command (stdio only, required) — absolute path to the server binary or script.
• args (stdio only, optional) — array of command-line arguments passed to command.
• env (stdio only, optional) — key-value environment variables injected into the server process.
• url (http/sse, required) — full URL of the MCP endpoint.
• headers (http/sse, optional) — HTTP headers sent with every request. Use ${ENV_VAR} syntax to reference environment variables.

Scope Levels

• Project scope — settings.json in the repo root (or .claude/settings.json). Committed to the repo. All team members get these MCP servers when using Claude Code in this project.
• User scope — settings.local.json in the project root or ~/.claude/settings.json. Not committed. Use for personal credentials, local dev servers, and servers with secrets in the command or env.

Put the server name and transport in settings.json (project scope) so the team knows what MCP servers are available. Put the credentials (env vars, tokens) in settings.local.json (user scope) so they are never committed.

Auth Patterns

• stdio — pass credentials via env field in settings.local.json (never settings.json). Reference the same variable in your server binary.
• HTTP/SSE — use ${ENV_VAR} in headers.Authorization. Set the env var in your shell profile or CI secrets. Never hardcode tokens in settings.json.
• OAuth — handled by the MCP server itself. Claude Code passes the bearer token the server gives it; configure the OAuth flow in the server, not in Claude Code.

Common Errors

• permission denied (stdio) — the command binary is not executable. Fix: chmod +x /path/to/server.
• command not found (stdio) — the binary is not on the PATH that Claude Code sees at launch. Fix: use absolute path in command, or set PATH in the env field.
• connection refused (http/sse) — wrong url, or the server is not running. Fix: verify the URL is reachable and the server is started before launching Claude Code.
• auth failure (http/sse) — missing or expired token. Fix: check that the environment variable referenced in headers is set in the shell where you launch Claude Code.
• tool not appearing — server launched but no tools registered. Fix: run /mcp in Claude Code to see server status and error output.

/mcp Command Output

The /mcp slash command shows the status of all configured MCP servers. Understanding its output speeds up debugging.

# Example /mcp output
MCP Servers:
  my-db-server    [stdio]   CONNECTED   3 tools
    Tools: query_db, list_tables, describe_table
  remote-api      [http]    ERROR       failed to connect: connection refused
  streaming-svc   [sse]     CONNECTING  ...

# Field meanings:
# Server name    — matches the name field in settings.json
# [transport]    — stdio, http, or sse
# Status         — CONNECTED, ERROR, CONNECTING, DISABLED
# N tools        — number of tools the server registered
# Tools list     — individual tool names (prefixed as name:tool in prompts)

If a server shows ERROR, the error message after the colon is the server's stderr output. Read it directly — it usually tells you exactly what's wrong (missing env var, bad config path, port conflict).

Continue to Claude Cert Academy