Claude Code MCP Servers

Claude Code is trapped on your machine until you fix it

Out of the box, Claude Code sees files on your disk. That's it. It can't check Slack, it can't read your PRs, it can't query your database.

MCP (Model Context Protocol) changes that. MCP servers are plugins that connect Claude Code to external services. Each one gives Claude Code the ability to read from or write to a tool you already use.

One conversation. Slack context, GitHub PRs, database queries, Figma specs. That's the pitch, and it actually delivers.

How it works

An MCP server is a small program that translates between Claude Code and an external API. Think of it like a USB hub: Claude Code is your laptop, and the MCP servers are the adapters for every service you already use.

Claude Code  →  MCP Server  →  External Service
   "read PR #42"  →  GitHub MCP  →  GitHub API
                   ←  PR diff, comments, status

Each server exposes tools that Claude Code can call: things like get_file_contents, list_pull_requests, create_pull_request. Claude Code discovers them automatically and uses them when your prompt calls for it. You don't have to do anything special.

Popular MCP servers

You don't need all of these. Most people start with one or two and add more as they feel the pull.

Setting one up

MCP servers live in a .mcp.json file at your project root. GitHub is the easiest one to start with:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<your-token-here>"
      }
    }
  }
}

When Claude Code starts, it reads .mcp.json, launches the servers, discovers their tools. Now "show me my open PRs" just works.

For OAuth-based servers (Slack, Figma), there's an authorization flow instead of a static token. Each server's docs walk you through it.

A real setup: GitHub + Linear

Here's what a two-service config actually looks like:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<your-github-token>"
      }
    },
    "linear": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-linear"],
      "env": {
        "LINEAR_API_KEY": "<your-linear-key>"
      }
    }
  }
}

With both connected, you can say "Find the Linear ticket for the auth bug, then check if there's a related PR on GitHub." Claude Code coordinates across both in a single response. This is where it gets genuinely fun.

Security: take this seriously

MCP servers have real access to your tools. They run as processes on your machine with the credentials you provide. Treat them like any API integration you'd wire into production.

Only connect servers you trust. Stick to official or well-maintained community servers.

Use scoped tokens. Don't hand over your admin token. Create a personal access token with minimum permissions. For GitHub, read-only repo and PR access covers most workflows.

Keep tokens out of version control. Never commit .mcp.json with real tokens. Use environment variables instead:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN"
      }
    }
  }
}

Using $GITHUB_TOKEN reads from your shell environment. The actual secret stays out of the file. Add .mcp.json to .gitignore and share a .mcp.json.example template with your team.

Allow rules name the whole server. Since v2.1.299, a permission rule like mcp__github covers only the server named github, not one named github__internal. Write mcp__<server>__* with the server's full name. The same goes for the tools: list in a subagent definition.

When a server misbehaves

A tool shows in /mcp but Claude can't call it. Check the tool's full name, mcp__<server>__<tool>. Claude Code leaves out any tool whose full name is over 128 characters, because the Claude API rejects it, and the server's other tools keep working. A shorter server name in your config shortens every tool name on that server.

A remote server drops. Claude Code retries a dropped HTTP or SSE server up to five times, starting at one second and doubling the wait. In an interactive session it then marks the server as failed, and you reconnect it from /mcp. In claude -p and Agent SDK runs, a server that keeps failing with transient errors goes on retrying in the background for up to about half an hour. Stdio servers run on your machine and don't reconnect on their own.

Long tool descriptions get cut. Server instructions and tool descriptions sent up front stop at 4,096 characters. Descriptions Claude loads through tool search stop at 16,384. CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH replaces both limits with one number, so setting it to 8192 raises the first limit and lowers the second. Some servers Anthropic hosts at api.anthropic.com send theirs in full.

Building your own stdio server? Claude Code gives it little time to clean up when it disconnects. On macOS and Linux it sends SIGINT, then SIGTERM 100 milliseconds later, then SIGKILL after another 400. On Windows it closes stdin and ends the process tree 300 milliseconds later. Save state and remove lock files inside that window.

Getting started

Start with GitHub. It's the easiest to set up and the most immediately useful. Get it working before adding more.

Test with a simple query first. "List my open PRs" or "Show me recent Slack messages." If that works, the connection is solid.

Read the server docs. Five minutes reading specific token scopes and supported tools saves an hour of debugging. Every time.

Watch for rate limits. MCP servers make real API calls. "Search all 500 repos for security issues" will hit GitHub's rate limit fast. Be specific in your requests.