claude-howto/05-mcp/README.md

MCP (Model Context Protocol)

This folder contains comprehensive documentation and examples for MCP server configurations and usage with Claude Code.

Overview

MCP (Model Context Protocol) is a standardized way for Claude to access external tools, APIs, and real-time data sources. Unlike Memory, MCP provides live access to changing data.

Key characteristics:

• Real-time access to external services
• Live data synchronization
• Extensible architecture
• Secure authentication
• Tool-based interactions

MCP Architecture

graph TB
    A["Claude"]
    B["MCP Server"]
    C["External Service"]

    A -->|Request: list_issues| B
    B -->|Query| C
    C -->|Data| B
    B -->|Response| A

    A -->|Request: create_issue| B
    B -->|Action| C
    C -->|Result| B
    B -->|Response| A

MCP Ecosystem

graph TB
    A["Claude"] -->|MCP| B["Filesystem<br/>MCP Server"]
    A -->|MCP| C["GitHub<br/>MCP Server"]
    A -->|MCP| D["Database<br/>MCP Server"]
    A -->|MCP| E["Slack<br/>MCP Server"]
    A -->|MCP| F["Google Docs<br/>MCP Server"]

    B -->|File I/O| G["Local Files"]
    C -->|API| H["GitHub Repos"]
    D -->|Query| I["PostgreSQL/MySQL"]
    E -->|Messages| J["Slack Workspace"]
    F -->|Docs| K["Google Drive"]

MCP Installation Methods

Claude Code supports multiple transport protocols for MCP server connections:

HTTP Transport (Recommended)

# Basic HTTP connection
claude mcp add --transport http notion https://mcp.notion.com/mcp

# HTTP with authentication header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Stdio Transport (Local)

For locally running MCP servers:

# Local Node.js server
claude mcp add --transport stdio myserver -- npx @myorg/mcp-server

# With environment variables
claude mcp add --transport stdio myserver --env KEY=value -- npx server

SSE Transport (Deprecated)

Server-Sent Events transport is deprecated but still supported:

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

Windows-Specific Note

On native Windows (not WSL), use cmd /c for npx commands:

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

MCP Setup Process

sequenceDiagram
    participant User
    participant Claude as Claude Code
    participant Config as Config File
    participant Service as External Service

    User->>Claude: Type /mcp
    Claude->>Claude: List available MCP servers
    Claude->>User: Show options
    User->>Claude: Select GitHub MCP
    Claude->>Config: Update configuration
    Config->>Claude: Activate connection
    Claude->>Service: Test connection
    Service-->>Claude: Authentication successful
    Claude->>User: ✅ MCP connected!

MCP Scopes

MCP configurations can be stored at different scopes with varying levels of sharing:

Scope	Location	Description	Shared With	Requires Approval
Local (default)	~/.claude.json	Private to current user	Just you	No
Project	.mcp.json	Checked into git repository	Team members	Yes (first use)
User	~/.claude.json	Available across all projects	Just you	No

Using Project Scope

Store project-specific MCP configurations in .mcp.json:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.github.com/mcp"
    }
  }
}

Team members will see an approval prompt on first use of project MCPs.

MCP Configuration Management

Adding MCP Servers

# Add HTTP-based server
claude mcp add --transport http github https://api.github.com/mcp

# Add local stdio server
claude mcp add --transport stdio database -- npx @company/db-server

# List all MCP servers
claude mcp list

# Get details on specific server
claude mcp get github

# Remove an MCP server
claude mcp remove github

# Reset project-specific approval choices
claude mcp reset-project-choices

# Import from Claude Desktop
claude mcp add-from-claude-desktop

Available MCP Servers Table

MCP Server	Purpose	Common Tools	Auth	Real-time
Filesystem	File operations	read, write, delete	OS permissions	✅ Yes
GitHub	Repository management	list_prs, create_issue, push	OAuth	✅ Yes
Slack	Team communication	send_message, list_channels	Token	✅ Yes
Database	SQL queries	query, insert, update	Credentials	✅ Yes
Google Docs	Document access	read, write, share	OAuth	✅ Yes
Asana	Project management	create_task, update_status	API Key	✅ Yes
Stripe	Payment data	list_charges, create_invoice	API Key	✅ Yes
Memory	Persistent memory	store, retrieve, delete	Local	❌ No

Practical Examples

Example 1: GitHub MCP Configuration

File: .claude/mcp.json

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

Available GitHub MCP Tools:

Pull Request Management

• list_prs - List all PRs in repository
• get_pr - Get PR details including diff
• create_pr - Create new PR
• update_pr - Update PR description/title
• merge_pr - Merge PR to main branch
• review_pr - Add review comments

Example request:

/mcp__github__get_pr 456

# Returns:
Title: Add dark mode support
Author: @alice
Description: Implements dark theme using CSS variables
Status: OPEN
Reviewers: @bob, @charlie

Issue Management

• list_issues - List all issues
• get_issue - Get issue details
• create_issue - Create new issue
• close_issue - Close issue
• add_comment - Add comment to issue

Repository Information

• get_repo_info - Repository details
• list_files - File tree structure
• get_file_content - Read file contents
• search_code - Search across codebase

Commit Operations

• list_commits - Commit history
• get_commit - Specific commit details
• create_commit - Create new commit

Setup:

export GITHUB_TOKEN="your_github_token"
cp github-mcp.json ~/.claude/mcp.json

Environment Variable Expansion in Configuration

MCP configurations support environment variable expansion with fallback defaults:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}",
        "X-Custom-Header": "${CUSTOM_HEADER:-default-value}"
      }
    }
  }
}

Variables are expanded at runtime:

• ${VAR} - Uses environment variable, error if not set
• ${VAR:-default} - Uses environment variable, falls back to default if not set

Example 2: Database MCP Setup

Configuration:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-database"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost/mydb"
      }
    }
  }
}

Example Usage:

User: Fetch all users with more than 10 orders

Claude: I'll query your database to find that information.

# Using MCP database tool:
SELECT u.*, COUNT(o.id) as order_count
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
GROUP BY u.id
HAVING COUNT(o.id) > 10
ORDER BY order_count DESC;

# Results:
- Alice: 15 orders
- Bob: 12 orders
- Charlie: 11 orders

Setup:

export DATABASE_URL="postgresql://user:pass@localhost/mydb"
cp database-mcp.json ~/.claude/mcp.json

Example 3: Multi-MCP Workflow

Scenario: Daily Report Generation

# Daily Report Workflow using Multiple MCPs

## Setup
1. GitHub MCP - fetch PR metrics
2. Database MCP - query sales data
3. Slack MCP - post report
4. Filesystem MCP - save report

## Workflow

### Step 1: Fetch GitHub Data
/mcp__github__list_prs completed:true last:7days

Output:
- Total PRs: 42
- Average merge time: 2.3 hours
- Review turnaround: 1.1 hours

### Step 2: Query Database
SELECT COUNT(*) as sales, SUM(amount) as revenue
FROM orders
WHERE created_at > NOW() - INTERVAL '1 day'

Output:
- Sales: 247
- Revenue: $12,450

### Step 3: Generate Report
Combine data into HTML report

### Step 4: Save to Filesystem
Write report.html to /reports/

### Step 5: Post to Slack
Send summary to #daily-reports channel

Final Output:
✅ Report generated and posted
📊 47 PRs merged this week
💰 $12,450 in daily sales

Setup:

export GITHUB_TOKEN="your_github_token"
export DATABASE_URL="postgresql://user:pass@localhost/mydb"
export SLACK_TOKEN="your_slack_token"
cp multi-mcp.json ~/.claude/mcp.json

Example 4: Filesystem MCP Operations

Configuration:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    }
  }
}

Available Operations:

Operation	Command	Purpose
List files	ls ~/projects	Show directory contents
Read file	cat src/main.ts	Read file contents
Write file	create docs/api.md	Create new file
Edit file	edit src/app.ts	Modify file
Search	grep "async function"	Search in files
Delete	rm old-file.js	Delete file

Setup:

cp filesystem-mcp.json ~/.claude/mcp.json

MCP vs Memory: Decision Matrix

graph TD
    A["Need external data?"]
    A -->|No| B["Use Memory"]
    A -->|Yes| C["Does it change frequently?"]
    C -->|No/Rarely| B
    C -->|Yes/Often| D["Use MCP"]

    B -->|Stores| E["Preferences<br/>Context<br/>History"]
    D -->|Accesses| F["Live APIs<br/>Databases<br/>Services"]

    style B fill:#e1f5ff
    style D fill:#fff9c4

Request/Response Pattern

sequenceDiagram
    participant App as Claude
    participant MCP as MCP Server
    participant DB as Database

    App->>MCP: Request: "SELECT * FROM users WHERE id=1"
    MCP->>DB: Execute query
    DB-->>MCP: Result set
    MCP-->>App: Return parsed data
    App->>App: Process result
    App->>App: Continue task

    Note over MCP,DB: Real-time access<br/>No caching

Environment Variables

Store sensitive credentials in environment variables:

# ~/.bashrc or ~/.zshrc
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxx"
export DATABASE_URL="postgresql://user:pass@localhost/mydb"
export SLACK_TOKEN="xoxb-xxxxxxxxxxxxx"

Then reference them in MCP config:

{
  "env": {
    "GITHUB_TOKEN": "${GITHUB_TOKEN}"
  }
}

Claude as MCP Server

Claude Code itself can act as an MCP server for other applications:

claude mcp serve

This starts Claude Code in MCP server mode, allowing other MCP clients to connect and use Claude's capabilities as a service.

Managed MCP Configuration (Enterprise)

For enterprise deployments, MCP servers can be managed centrally via configuration files:

Location:

• macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
• Linux: ~/.config/ClaudeCode/managed-mcp.json
• Windows: %APPDATA%\ClaudeCode\managed-mcp.json

Features:

• Allowlist/denylist controls
• Restrict by server name, command, or URL
• Organization-wide MCP policies
• Prevents unauthorized server connections

Example configuration:

{
  "allowlist": [
    {
      "serverName": "github",
      "serverUrl": "https://api.github.com/mcp"
    },
    {
      "serverName": "company-internal",
      "serverCommand": "company-mcp-server"
    }
  ],
  "denylist": [
    {
      "serverName": "untrusted-*"
    }
  ]
}

Best Practices

Security Considerations

Do's ✅

• Use environment variables for all credentials
• Rotate tokens and API keys regularly (monthly recommended)
• Use read-only tokens when possible
• Limit MCP server access scope to minimum required
• Monitor MCP server usage and access logs
• Use OAuth for external services when available
• Implement rate limiting on MCP requests
• Test MCP connections before production use
• Document all active MCP connections
• Keep MCP server packages updated

Don'ts ❌

• Don't hardcode credentials in config files
• Don't commit tokens or secrets to git
• Don't share tokens in team chats or emails
• Don't use personal tokens for team projects
• Don't grant unnecessary permissions
• Don't ignore authentication errors
• Don't expose MCP endpoints publicly
• Don't run MCP servers with root/admin privileges
• Don't cache sensitive data in logs
• Don't disable authentication mechanisms

Configuration Best Practices

1. Version Control: Keep .claude/mcp.json in git but use environment variables for secrets
2. Least Privilege: Grant minimum permissions needed for each MCP server
3. Isolation: Run different MCP servers in separate processes when possible
4. Monitoring: Log all MCP requests and errors for audit trails
5. Testing: Test all MCP configurations before deploying to production

Performance Tips

• Cache frequently accessed data at the application level
• Use MCP queries that are specific to reduce data transfer
• Monitor response times for MCP operations
• Consider rate limiting for external APIs
• Use batching when performing multiple operations

Installation Instructions

Prerequisites

• Node.js and npm installed
• Claude Code CLI installed
• API tokens/credentials for external services

Step-by-Step Setup

1. Create MCP configuration file:

mkdir -p ~/.claude
touch ~/.claude/mcp.json

2. Add your first MCP server (example: GitHub):

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

3. Set environment variables:

export GITHUB_TOKEN="your_github_personal_access_token"

4. Test the connection:

claude /mcp

5. Use MCP tools:

/mcp__github__list_prs
/mcp__github__create_issue "Title" "Description"

Installation for Specific Services

GitHub MCP:

npm install -g @modelcontextprotocol/server-github

Database MCP:

npm install -g @modelcontextprotocol/server-database

Filesystem MCP:

npm install -g @modelcontextprotocol/server-filesystem

Slack MCP:

npm install -g @modelcontextprotocol/server-slack

Troubleshooting

MCP Server Not Found

# Verify MCP server is installed
npm list -g @modelcontextprotocol/server-github

# Install if missing
npm install -g @modelcontextprotocol/server-github

Authentication Failed

# Verify environment variable is set
echo $GITHUB_TOKEN

# Re-export if needed
export GITHUB_TOKEN="your_token"

# Verify token has correct permissions
# Check GitHub token scopes at: https://github.com/settings/tokens

Connection Timeout

• Check network connectivity: ping api.github.com
• Verify API endpoint is accessible
• Check rate limits on API
• Try increasing timeout in config
• Check for firewall or proxy issues

MCP Server Crashes

• Check MCP server logs: ~/.claude/logs/
• Verify all environment variables are set
• Ensure proper file permissions
• Try reinstalling the MCP server package
• Check for conflicting processes on the same port

Related Concepts

Memory vs MCP

• Memory: Stores persistent, unchanging data (preferences, context, history)
• MCP: Accesses live, changing data (APIs, databases, real-time services)

When to Use Each

• Use Memory for: User preferences, conversation history, learned context
• Use MCP for: Current GitHub issues, live database queries, real-time data

Integration with Other Claude Features

• Combine MCP with Memory for rich context
• Use MCP tools in prompts for better reasoning
• Leverage multiple MCPs for complex workflows

Additional Resources

• Official MCP Documentation
• MCP Protocol Specification
• MCP GitHub Repository
• Available MCP Servers
• Claude Code CLI Reference
• Claude API Documentation