Claude Code MCP Server Setup: 3 Ways to Connect Tools

How Claude Code Discovers Tools

Claude Code reads a file called .mcp.json to find MCP servers. Each entry in this file defines a server name, its transport type, and the connection details. When Claude Code starts, it connects to every configured server and pulls a list of available tools. Those tools then appear in your session alongside built-in capabilities like file editing and shell access.

The .mcp.json file can live in two places: your project root (project-scoped) or your home directory (global, shared across all projects). Project-level entries override global ones if names collide.

There are three transport types you can use in this file. Each solves a different problem.

Method 1: Direct MCP Server (stdio Transport)

The simplest approach. You point Claude Code at an MCP server binary or script, and it spawns the process directly using standard input/output for communication.

Step 1: Install the MCP Server

Most MCP servers are published as npm packages. Install them globally or within your project:

# Example: install the Playwright MCP server
npm install -g @anthropic/mcp-playwright

# Example: install a Python MCP server
pip install mcp-server-semgrep

Step 2: Add the Entry to .mcp.json

Create .mcp.json in your project root with a "command" transport entry:

// .mcp.json — stdio transport
{
  "playwright": {
    "type": "stdio",
    "command": "npx",
    "args": ["@anthropic/mcp-playwright"]
  },
  "semgrep": {
    "type": "stdio",
    "command": "python",
    "args": ["-m", "mcp_server_semgrep"],
    "env": {
      "SEMGREP_APP_TOKEN": "your-token-here"
    }
  }
}

Step 3: Restart Claude Code

Claude Code reads .mcp.json on startup. After adding entries, restart your session. The tools from each server will appear automatically.

When to Use stdio

• You use 1-3 MCP servers
• You run a single Claude Code session at a time
• You need the simplest possible setup

The Scaling Problem

Every stdio entry spawns a new operating system process. If you configure 10 MCP servers and open 5 Claude Code sessions, that is 50 processes. Each Node.js-based server consumes 50-200 MB of RAM. At scale, stdio transport can exhaust system memory. We hit this wall running 8 sessions with 50 tools: over 400 Node.js processes consuming 128 GB of RAM.

Method 2: HTTP Hub (Shared Server)

Instead of spawning a process per session, run your MCP servers once as HTTP services and point Claude Code at their URLs. This is the HTTP transport method.

Step 1: Start Your MCP Servers as HTTP Services

Most MCP servers support an HTTP mode. Run them on designated ports and leave them running in the background:

# Start Playwright MCP on port 18901
npx @anthropic/mcp-playwright --http --port 18901 &

# Start Semgrep MCP on port 18902
python -m mcp_server_semgrep --http --port 18902 &

# Start Context7 on port 18903
npx @context7/mcp --http --port 18903 &

Step 2: Configure .mcp.json with HTTP Transport

// .mcp.json — HTTP transport (shared hub)
{
  "playwright": {
    "type": "http",
    "url": "http://localhost:18901/mcp"
  },
  "semgrep": {
    "type": "http",
    "url": "http://localhost:18902/mcp"
  },
  "context7": {
    "type": "http",
    "url": "http://localhost:18903/mcp"
  }
}

When to Use an HTTP Hub

• You run multiple Claude Code sessions simultaneously
• You use 5-20 MCP servers
• You want each server running once regardless of session count
• You are comfortable managing long-running processes

The Remaining Problem

The HTTP hub solves the per-session process multiplication. But you still manage every server individually: installation, updates, port assignment, API keys, process monitoring, and restarts. Each new tool adds operational overhead. At 20+ tools, you are effectively running a small distributed system that has nothing to do with the actual AI work.

Method 3: Through a Gateway (One Config, All Tools)

A managed MCP gateway runs the tools on its infrastructure and exposes them through a single MCP endpoint. You configure one entry and get access to every tool in the registry.

Step 1: Get an API Key

Sign up at toolroute.ai and generate an API key. This single key authenticates against all 87 tools.

Step 2: Add One Entry to .mcp.json

// .mcp.json — ToolRoute gateway (87 tools, one line)
{
  "toolroute": {
    "type": "http",
    "url": "https://toolroute.ai/mcp",
    "headers": {
      "Authorization": "Bearer tr_live_xxx"
    }
  }
}

That is the entire configuration. No local installations, no port management, no per-tool API keys. Claude Code connects to the gateway on startup and receives the full tool catalog.

Step 3: Use Any Tool Immediately

Once connected, every tool in the registry is available in your session. Search the web with Tavily. Scan code with Semgrep. Query documentation with Context7. Send emails with Resend. Manage DNS with GoDaddy. All through the same gateway endpoint.

> Use context7 to look up the Next.js App Router docs
  [ToolRoute routes to Context7 adapter]
  Found 47 documentation chunks for next.js/app-router...

> Scan this repo with semgrep for SQL injection
  [ToolRoute routes to Semgrep adapter]
  Scanning 142 files... 0 findings.

> Search Stripe for customer with email user@example.com
  [ToolRoute routes to Stripe adapter]
  Found 1 customer: cus_abc123...

When to Use a Gateway

• You want access to many tools without managing any servers
• You run multiple concurrent Claude Code sessions
• You do not want to manage per-tool API keys
• You value zero setup time over latency optimization

Comparison: All Three Methods Side by Side

Mixing Methods: The Hybrid Approach

You are not locked into a single method. A common pattern is to use a gateway for the long tail of tools you need occasionally, while running a few high-frequency or custom tools locally via HTTP hub.

// .mcp.json — hybrid: gateway + local custom tools
{
  "toolroute": {
    "type": "http",
    "url": "https://toolroute.ai/mcp",
    "headers": {
      "Authorization": "Bearer tr_live_xxx"
    }
  },
  "my-custom-db": {
    "type": "http",
    "url": "http://localhost:18910/mcp"
  },
  "internal-api": {
    "type": "stdio",
    "command": "node",
    "args": ["./tools/internal-mcp.js"]
  }
}

This gives you the best of both worlds: 87 tools from the gateway with zero infrastructure, plus your proprietary tools running locally where you have full control.

Troubleshooting Common Issues

Tools Not Appearing After Config Change

Claude Code reads .mcp.json on startup. If you edit the file mid-session, restart Claude Code for the changes to take effect. Also verify the JSON is valid: a trailing comma or missing bracket will silently prevent loading.

Connection Refused on HTTP Transport

Ensure the target server is running before starting Claude Code. Check that the port matches your configuration and that no firewall is blocking localhost connections.

stdio Server Crashes Mid-Session

When a stdio process crashes, tools from that server become unavailable. Claude Code does not automatically restart stdio processes. You will need to restart the session. This is one reason to prefer HTTP transport or a gateway for production workflows.

High Memory Usage

If you see system memory climbing, check your process count. Each stdio MCP server spawns per session. Switch high-usage servers to HTTP transport, or move the entire tool stack to a gateway.

Which Method Should You Choose?

Most teams start with stdio for one or two tools and evolve toward HTTP hub or gateway as their tool count grows. The Model Context Protocol is transport-agnostic by design, so switching methods only requires changing .mcp.json entries, not rewriting any agent logic.