Claude Code connects to MCP servers through a .mcp.json file in your project root. Two transport options: stdio for local servers, HTTP for remote ones.

This guide assumes you have Claude Code installed.

stdio Transport (Local Server)

The server runs as a child process. Claude Code spawns it, communicates over stdin/stdout, and kills it when the session ends.

Create .mcp.json in your project root:

{
  "mcpServers": {
    "my-tools": {
      "command": "npx",
      "args": ["tsx", "/full/path/to/src/stdio-server.ts"]
    }
  }
}

The key (my-tools) is the display name in Claude Code. The path must be absolute.

Restart Claude Code (or start a new session) to pick up the config.

HTTP Transport (Remote Server)

The server runs as a web service. Claude Code connects over HTTP POST.

{
  "mcpServers": {
    "my-tools": {
      "type": "http",
      "url": "http://localhost:3100/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-token"
      }
    }
  }
}

The headers field is optional. Include it if your server requires authentication.

Verify the Connection

After restarting Claude Code, check that your tools are registered:

Start a Claude Code session in the project directory
Ask Claude to list available tools, or just use one — Claude will discover them automatically
Check the output for your tool names

If something is wrong, Claude Code will show an error during initialization. Common issues are below.

Troubleshooting

spawn ENOENT error: Claude Code can't find the command. Common causes:

npx isn't in PATH — install Node.js 20+ and ensure npx is available globally
Wrong path to the server file — use an absolute path, not relative
Missing tsx — run npm install -g tsx or use npx tsx (the npx prefix handles this)

Server starts but no tools appear: Your server might be writing to stdout during startup. In stdio mode, stdout is reserved for JSON-RPC. Use console.error() for any logging.

HTTP connection refused: The server isn't running or is bound to the wrong interface. If the server is on another machine, make sure it binds to 0.0.0.0, not 127.0.0.1.

Tools appear but calls fail: Check that express.json() middleware is applied before the MCP route. Without it, the request body is undefined.

Multiple Servers

You can connect to multiple MCP servers at once:

{
  "mcpServers": {
    "local-tools": {
      "command": "npx",
      "args": ["tsx", "/path/to/stdio-server.ts"]
    },
    "remote-tools": {
      "type": "http",
      "url": "http://10.0.0.5:3100/mcp"
    },
    "n8n-tools": {
      "type": "http",
      "url": "http://10.0.0.5:5678/mcp/my-tools"
    }
  }
}

Each server's tools are available simultaneously. Tool names must be unique across all connected servers.

Configuration Notes

Scope: .mcp.json is per-project. Place it in the root of each project that needs MCP tools. There's also a global config at ~/.claude/.mcp.json for tools you want available everywhere.
Environment variables: stdio servers inherit the environment from the env field in the config. Use this for API keys or database URLs without hardcoding them.
Hot reload: Changes to .mcp.json require restarting Claude Code. There's no hot reload — exit and re-enter the session.
Cost: MCP tool calls count toward your Anthropic API usage like any other tool use. A typical MCP call adds a few hundred tokens to the conversation.

ConnectingClaudeCodetoanMCPServer