MCP Integration

MCP Integration

Model Context Protocol (MCP) integration for connecting Claude Code to external tools and services.

What is MCP?

Model Context Protocol enables Claude Code to:

• Connect to external tools and services
• Access resources (files, databases, APIs)
• Use custom tools
• Provide prompts and completions

Configuration

MCP servers are configured in .claude/mcp.json:

Basic Configuration

{
  "mcpServers": {
    "server-name": {
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "VAR_NAME": "value"
      }
    }
  }
}

Example Configuration

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/db"
      }
    }
  }
}

Common MCP Servers

Filesystem Access

{
  "filesystem": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-filesystem",
      "/path/to/allowed/files"
    ]
  }
}

Capabilities:

• Read/write files
• List directories
• File search
• Path restrictions for security

GitHub Integration

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

Capabilities:

• Repository access
• Issues and PRs
• Code search
• Workflow management

PostgreSQL Database

{
  "postgres": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres"],
    "env": {
      "DATABASE_URL": "${DATABASE_URL}"
    }
  }
}

Capabilities:

• Query execution
• Schema inspection
• Transaction management
• Connection pooling

Brave Search

{
  "brave-search": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
    "env": {
      "BRAVE_API_KEY": "${BRAVE_API_KEY}"
    }
  }
}

Capabilities:

• Web search
• News search
• Local search
• Result filtering

Puppeteer (Browser Automation)

{
  "puppeteer": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
  }
}

Capabilities:

• Browser automation
• Screenshots
• PDF generation
• Web scraping

Remote MCP Servers

Connect to MCP servers over HTTP/SSE:

Basic Remote Server

{
  "mcpServers": {
    "remote-service": {
      "url": "https://api.example.com/mcp"
    }
  }
}

With Authentication

{
  "mcpServers": {
    "remote-service": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}",
        "X-Custom-Header": "value"
      }
    }
  }
}

With Proxy

{
  "mcpServers": {
    "remote-service": {
      "url": "https://api.example.com/mcp",
      "proxy": "http://proxy.company.com:8080"
    }
  }
}

Environment Variables

Use environment variables for sensitive data:

.env File

# .claude/.env
GITHUB_TOKEN=ghp_xxxxx
DATABASE_URL=postgresql://user:pass@localhost/db
BRAVE_API_KEY=BSAxxxxx
API_TOKEN=token_xxxxx

Reference in mcp.json

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

Testing MCP Servers

Inspector Tool

npx @modelcontextprotocol/inspector

Opens web UI for testing MCP servers:

• List available tools
• Test tool invocations
• View resources
• Debug connections

Manual Testing

# Test server command
npx -y @modelcontextprotocol/server-filesystem /tmp

# Check server output
echo '{"jsonrpc":"2.0","method":"initialize","params":{}}' | \
  npx -y @modelcontextprotocol/server-filesystem /tmp

Creating Custom MCP Servers

Python Server

from mcp.server import Server
from mcp.server.stdio import stdio_server

server = Server("my-server")

@server.tool()
async def my_tool(arg: str) -> str:
    """Tool description"""
    return f"Result: {arg}"

if __name__ == "__main__":
    stdio_server(server)

Configuration

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["path/to/server.py"]
    }
  }
}

Node.js Server

import { Server } from "@modelcontextprotocol/server-node";

const server = new Server("my-server");

server.tool({
  name: "my-tool",
  description: "Tool description",
  parameters: { arg: "string" }
}, async ({ arg }) => {
  return `Result: ${arg}`;
});

server.listen();

Security Considerations

Filesystem Access

• Restrict to specific directories
• Use read-only access when possible
• Validate file paths
• Monitor access logs

API Credentials

• Use environment variables
• Never commit credentials
• Rotate keys regularly
• Implement least-privilege access

Network Access

• Whitelist allowed domains
• Use HTTPS only
• Implement timeouts
• Rate limit requests

Remote Servers

• Validate server certificates
• Use authentication
• Implement request signing
• Monitor for anomalies

Troubleshooting

Server Not Starting

# Check server command
npx -y @modelcontextprotocol/server-filesystem /tmp

# Verify environment variables
echo $GITHUB_TOKEN

# Check logs
cat ~/.claude/logs/mcp-*.log

Connection Errors

# Test network connectivity
curl https://api.example.com/mcp

# Verify proxy settings
echo $HTTP_PROXY

# Check firewall rules

Permission Errors

# Verify file permissions
ls -la /path/to/allowed/files

# Check user permissions
whoami
groups

Tool Not Found

• Verify server is running
• Check server configuration
• Inspect server capabilities
• Review tool registration

Best Practices

Configuration Management

• Use environment variables for secrets
• Document server purposes
• Version control mcp.json (without secrets)
• Test configurations thoroughly

Performance

• Use local servers when possible
• Implement caching
• Set appropriate timeouts
• Monitor resource usage

Maintenance

• Update servers regularly
• Monitor server health
• Review access logs
• Clean up unused servers

See Also

• MCP specification: https://modelcontextprotocol.io
• Creating MCP servers: references/api-reference.md
• Security best practices: references/best-practices.md
• Troubleshooting: references/troubleshooting.md