MCP Servers

Claude Code is both an MCP client and an MCP server. As a client, it connects to any number of running MCP servers and their tools appear in Claude's tool list automatically. That's what powers the first-party integrations you see in Claude Code (browser control, filesystem, GitHub, etc.): they're all MCP servers under the hood.

The tool naming convention tells you where a tool lives: mcp__<server>__<tool>. So mcp__playwright__browser_screenshot is the browser_screenshot tool from the playwright server. This pattern matters when you're writing hooks or checking what's available.

How you use it day-to-day

• Add a server via CLI. claude mcp add <name> <command> [args...] for stdio-based servers (most npm packages), or claude mcp add --transport sse <name> <url> for remote SSE endpoints. This is the fastest way to try a server.
• Commit a team config. Drop a .mcp.json at the project root with the mcpServers block and check it in. Everyone on the team gets the same servers without any manual setup steps.
• Pass auth via env. Tokens and secrets go in the server's env block inside the JSON config, e.g. "GITHUB_TOKEN": "${GITHUB_TOKEN}". The server process inherits those values; nothing is hardcoded.
• Debug connection problems. Launch with claude --mcp-debug to see startup output, tool registration, and protocol errors in real time.
• Hook on MCP tool calls. Use mcp__<server>__.* as the matcher in PreToolUse hooks to log, validate, or block specific server operations, the same hook system as built-in tools.

Gotchas

• Scope matters. CLI-added servers are user-scoped (available everywhere). .mcp.json in a project root is project-scoped. Choose the right level; don't add a project-specific secret-bearing server user-wide.
• Servers must be running. Claude Code doesn't start MCP servers lazily. If the process doesn't start (missing binary, bad path), the tools simply won't appear. Check --mcp-debug output, not just the tool list.
• Auth is your problem. MCP has no built-in auth handshake for most servers. You are responsible for getting the token into the env before Claude starts.
• Tool count bloat. Each server can register many tools. Stacking several large servers inflates the tool list, which can push context usage up and slow tool selection. Add only what you actively use.

SDK usage: when calling Claude Code programmatically via the Agent SDK, pass mcp_servers (Python) / mcpServers (TypeScript) in the options object. The SDK spins up and tears down the server process alongside the query, so no separate lifecycle management is needed.