MCP Server Integration

The Model Context Protocol (MCP) transforms Claude Code from a coding assistant into a connected automation platform. With MCP servers, Claude can manage GitHub pull requests, query databases, automate browsers, send Slack messages, and interact with virtually any external system.

Think of MCP as a universal adapter layer. Each MCP server exposes tools that Claude can call just like its built-in capabilities—but instead of reading local files, it's creating PRs, running SQL queries, or triggering CI pipelines.

How MCP Works

MCP servers run as separate processes that Claude Code communicates with. When you add an MCP server, its tools become available in your Claude session. The server handles the actual API calls, authentication, and data transformation.

The naming convention for MCP tools follows this pattern:

mcp__<server-name>__<tool-name>

For example, mcp__github__create_pull_request or mcp__slack__post_message.

Adding MCP Servers

Claude Code supports three transport methods for MCP servers:

HTTP Transport (Recommended for Remote)

claude mcp add --transport http github https://mcp.github.com/api

HTTP servers are ideal for hosted services and team-shared infrastructure.

Stdio Transport (Local Execution)

claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github

Stdio servers run as local processes, perfect for development and tools that need filesystem access.

SSE Transport (Deprecated)

claude mcp add --transport sse legacy-server https://example.com/sse

Server-Sent Events transport is deprecated—avoid for new integrations.

Configuration Scopes

MCP servers can be configured at three levels:

Scope	File	Use Case	Shared
Local	~/.claude.json	Personal, experimental	No
Project	.mcp.json	Team-shared via git	Yes
User	~/.claude.json	Cross-project utilities	No

Precedence Order

Local > Project > User

If the same server is configured at multiple levels, the local configuration wins.

Project Configuration (.mcp.json)

The recommended approach for teams is checking .mcp.json into your repository:

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"]
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Note the ${DATABASE_URL} syntax—environment variables are expanded at runtime. This keeps secrets out of your repository while allowing team-shared configuration.

Environment Variable Expansion

MCP configurations support full environment variable expansion:

{
  "mcpServers": {
    "api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

The ${VAR:-default} syntax provides fallback values.

Essential MCP Servers

GitHub

The most commonly used MCP server, enabling full GitHub workflow automation:

claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github

Capabilities:

• Create and manage pull requests
• Search and update issues
• Trigger CI/CD workflows
• Analyze commits and diffs
• Manage repository settings

Example interaction:

"Create a PR from my current branch to main with a summary of the changes"

Claude reads your git diff, generates a description, and creates the PR—all through the MCP server.

Playwright

Browser automation for testing and web interaction:

claude mcp add --transport stdio playwright -- npx @anthropic-ai/mcp-server-playwright

Capabilities:

• Navigate web pages
• Fill forms and click buttons
• Take screenshots
• Extract page content
• Run end-to-end tests

Example interaction:

"Go to our staging site, log in, and verify the dashboard loads correctly"

PostgreSQL / Supabase

Database access for querying and schema management:

claude mcp add --transport stdio postgres -- npx @modelcontextprotocol/server-postgres

Capabilities:

• Run SQL queries
• Explore schema
• Analyze query performance
• Generate migrations

Example interaction:

"Show me the users who signed up this week and their subscription status"

Filesystem (Enhanced)

Extended file operations beyond Claude's built-in tools:

claude mcp add --transport stdio filesystem -- npx @modelcontextprotocol/server-filesystem

Capabilities:

• Watch for file changes
• Bulk file operations
• Advanced search patterns
• File metadata access

Slack

Team communication integration:

claude mcp add --transport stdio slack -- npx @anthropic-ai/mcp-server-slack

Capabilities:

• Post messages to channels
• Reply to threads
• Search message history
• Manage channel membership

MCP Commands Reference

List Servers

claude mcp list

Shows all configured MCP servers and their status.

Get Server Details

claude mcp get github

Displays configuration and available tools for a specific server.

Remove Server

claude mcp remove github

In-Session Authentication

For servers requiring OAuth:

/mcp

This opens the MCP authentication flow within Claude Code.

Check Status

/mcp status

Shows connection status for all servers.

Permission Management

MCP tools require permission like built-in tools. Configure them in your settings:

Allow All Tools from a Server

{
  "permissions": {
    "allow": ["mcp__github__*"]
  }
}

Specific Tool Permissions

{
  "permissions": {
    "allow": [
      "mcp__github__search_repositories",
      "mcp__github__get_issue"
    ],
    "ask": [
      "mcp__github__create_pull_request"
    ],
    "deny": [
      "mcp__github__delete_repository"
    ]
  }
}

Building Custom MCP Servers

For internal APIs or custom integrations, you can build your own MCP server. The protocol is straightforward:

Basic Structure

import { Server } from "@modelcontextprotocol/sdk/server";

const server = new Server({
  name: "my-custom-server",
  version: "1.0.0"
});

server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "my_tool",
      description: "Does something useful",
      inputSchema: {
        type: "object",
        properties: {
          param: { type: "string", description: "Input parameter" }
        },
        required: ["param"]
      }
    }
  ]
}));

server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "my_tool") {
    const result = await doSomethingUseful(request.params.arguments.param);
    return { content: [{ type: "text", text: result }] };
  }
});

server.connect(process.stdin, process.stdout);

Registering Your Server

claude mcp add --transport stdio my-server -- node /path/to/server.js

Output Limits and Performance

MCP responses have default limits to prevent context bloat:

• Warning threshold: 10,000 tokens
• Hard limit: 25,000 tokens

For servers that return large amounts of data, configure higher limits:

export MAX_MCP_OUTPUT_TOKENS=50000

Or in your MCP config:

{
  "mcpServers": {
    "data-server": {
      "type": "stdio",
      "command": "node",
      "args": ["server.js"],
      "outputLimits": {
        "maxTokens": 50000
      }
    }
  }
}

Team Deployment Patterns

Development Environment

Each developer has personal servers in ~/.claude.json:

{
  "mcpServers": {
    "local-db": {
      "type": "stdio",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/dev"
      }
    }
  }
}

Shared Project Configuration

Common servers in .mcp.json (checked into git):

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"]
    }
  }
}

Enterprise Controlled

For organizations requiring strict control, use managed MCP configuration:

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "jira" }
  ],
  "deniedMcpServers": [
    { "serverName": "*" }
  ]
}

This allowlist pattern ensures only approved servers can be used.

Troubleshooting

Server Won't Connect

1. Check the command runs manually: npx @modelcontextprotocol/server-github
2. Verify environment variables are set
3. Check for port conflicts with lsof -i
4. Review Claude's verbose output: claude --verbose

Authentication Issues

Use /mcp to re-authenticate. For OAuth servers, tokens may expire and need renewal.

Slow Response Times

MCP servers add latency. For frequently-used operations:

• Consider caching in your server
• Pre-authenticate before sessions
• Use local servers for development

What's Next

MCP servers extend what Claude can do. In Part 4, we'll explore how to divide work across multiple specialized agents—subagents that work in parallel with isolated context.

Up next: Part 4: Multi-Agent Workflows & Subagents — Learn to orchestrate specialized AI agents that work in parallel on complex tasks.

---

Sources

• Claude Code MCP Documentation
• Model Context Protocol Specification
• MCP Server Directory
• Top MCP Servers for Claude Code