MCP (Model Context Protocol): Complete Guide

MCP (Model Context Protocol) is Claude Code’s plugin system that extends Claude’s capabilities by connecting to external tools, databases, and services. This guide covers everything you need to know to leverage MCP effectively.

What is MCP?

According to the official Anthropic documentation, MCP is a standardized protocol that allows AI assistants to:

• Access external data sources (databases, APIs, file systems)
• Execute specialized tools (Git, package managers, cloud services)
• Maintain persistent context (memory, knowledge graphs)
• Integrate with development tools (IDEs, CI/CD, project management)

Think of MCP servers as plugins that give Claude new abilities beyond its base capabilities.

MCP Architecture

┌─────────────────────────────────────────────────────────┐
│                    Claude Code CLI                       │
│  ┌─────────────────────────────────────────────────┐    │
│  │                 MCP Client                       │    │
│  │  Manages connections to MCP servers             │    │
│  └─────────────────────────────────────────────────┘    │
│            │              │              │               │
│            ▼              ▼              ▼               │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐     │
│  │ MCP Server 1 │ │ MCP Server 2 │ │ MCP Server 3 │     │
│  │ (filesystem) │ │   (memory)   │ │    (git)     │     │
│  └──────────────┘ └──────────────┘ └──────────────┘     │
│            │              │              │               │
│            ▼              ▼              ▼               │
│      Local Files    Knowledge     Git Repository        │
│                      Graph                               │
└─────────────────────────────────────────────────────────┘

Adding MCP Servers

Official CLI Method (Recommended)

From the Claude Code documentation, always use the CLI:

# Basic syntax
claude mcp add [--scope <scope>] <name> [options] -- <command>

# Scopes:
# --scope user     → ~/.claude/settings.json (all projects)
# --scope project  → .claude/settings.json (this project)

Common MCP Servers

1. Filesystem Access

claude mcp add --scope project filesystem \
  -- npx -y @modelcontextprotocol/server-filesystem .

Capabilities:

• Read/write files
• Create directories
• List directory contents
• File search and pattern matching

2. Memory (Knowledge Graph)

# IMPORTANT: Always use MEMORY_FILE_PATH for project isolation
claude mcp add --scope project memory \
  -e MEMORY_FILE_PATH=./.claude/memory.json \
  -- npx -y @modelcontextprotocol/server-memory

Capabilities:

• Persistent knowledge storage
• Entity and relationship tracking
• Cross-session memory
• Semantic search

⚠️ Critical: Without MEMORY_FILE_PATH, all projects share the same memory!

3. Git Operations

claude mcp add --scope project git \
  -- npx -y @modelcontextprotocol/server-git

Capabilities:

• Git status, log, diff
• Branch operations
• Commit history
• File blame

4. GitHub Integration

claude mcp add --scope user github \
  -e GITHUB_TOKEN=<your-token> \
  -- npx -y @modelcontextprotocol/server-github

Capabilities:

• Issues and PRs
• Repository management
• Code search
• Actions workflow

5. Sequential Thinking

claude mcp add --scope user sequential-thinking \
  -- npx -y @modelcontextprotocol/server-sequential-thinking

Capabilities:

• Structured reasoning
• Multi-step analysis
• Complex problem decomposition

6. Context7 (Live Documentation)

claude mcp add --scope user context7 \
  -- npx -y context7-mcp

Capabilities:

• Real-time official documentation
• Up-to-date library references
• Framework guidance

Database MCP Servers

PostgreSQL

claude mcp add --scope project postgres \
  -e DATABASE_URL="postgresql://user:pass@localhost:5432/db" \
  -- npx -y @modelcontextprotocol/server-postgres

Capabilities:

• Query execution
• Schema inspection
• Table operations
• Migration support

SQLite

claude mcp add --scope project sqlite \
  -e DATABASE_PATH="./data/app.db" \
  -- npx -y @modelcontextprotocol/server-sqlite

MongoDB

claude mcp add --scope project mongodb \
  -e MONGODB_URI="mongodb://localhost:27017/db" \
  -- npx -y @modelcontextprotocol/server-mongodb

Cloud Service MCP Servers

AWS

claude mcp add --scope user aws \
  -e AWS_ACCESS_KEY_ID=<key> \
  -e AWS_SECRET_ACCESS_KEY=<secret> \
  -e AWS_REGION=us-east-1 \
  -- npx -y @modelcontextprotocol/server-aws

Cloudflare

claude mcp add --scope user cloudflare \
  -e CLOUDFLARE_API_TOKEN=<token> \
  -- npx -y @anthropic/cloudflare-mcp

Vercel

claude mcp add --scope user vercel \
  -e VERCEL_TOKEN=<token> \
  -- npx -y vercel-mcp

MCP Configuration Files

Project Settings (.claude/settings.json)

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "./.claude/memory.json"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  },
  "enableAllProjectMcpServers": true
}

User Settings (~/.claude/settings.json)

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

MCP Scope and Hierarchy

MCP servers follow Claude Code’s four-layer hierarchy:

┌─────────────────────────────────────────────┐
│  Layer 1: Enterprise                         │
│  Location: /etc/claude-code/settings.json    │
│  Control: IT department                      │
│  Use: Restrict MCP servers via allowlist     │
├─────────────────────────────────────────────┤
│  Layer 2: User Global                        │
│  Location: ~/.claude/settings.json           │
│  Use: Personal MCP servers (github, etc.)    │
├─────────────────────────────────────────────┤
│  Layer 3: Project                            │
│  Location: .claude/settings.json             │
│  Use: Project-specific servers (db, memory)  │
├─────────────────────────────────────────────┤
│  Layer 4: Project Local                      │
│  Location: .claude/settings.local.json       │
│  Use: Personal overrides (gitignored)        │
└─────────────────────────────────────────────┘

Priority: Local > Project > User > Enterprise

MCP Context Cost

Each MCP server consumes context tokens. Be mindful of the cost:

MCP Server	Approx. Tokens	Recommendation
hubspot	~1,800	✅ Small, recommended
netlify	~2,000	✅ Small, recommended
figma	~2,500	✅ Acceptable
notion	Optimized	✅ Official optimization
vercel	~3,000	✅ Acceptable
stripe	~4,000	⚠️ Medium
linear	~6,200	⚠️ Large
atlassian	~7,100	⚠️ Large
asana	~12,800	❌ Too large
sentry	~14,000	❌ Too large, use sparingly

Best Practice: Only enable MCP servers you actively use. More servers = more context = higher cost and slower responses.

MCP Management Commands

# List all MCP servers
claude mcp list

# Add a new server
claude mcp add --scope project <name> -- <command>

# Remove a server
claude mcp remove --scope project <name>

# Check server status
claude mcp status

# Reset project MCP choices (troubleshooting)
claude mcp reset-project-choices

Using MCP in Practice

Example 1: Database Queries

With postgres MCP enabled:

User: "Show me users who signed up in the last 7 days"

Claude: [Uses postgres MCP]
  → Queries: SELECT * FROM users WHERE created_at > NOW() - INTERVAL '7 days'
  → Returns formatted results
  → Suggests indexes if query is slow

Example 2: Knowledge Persistence

With memory MCP enabled:

User: "Remember that we use Zod for all API validation"

Claude: [Uses memory MCP]
  → Creates entity: "API Validation"
  → Adds observation: "Use Zod for all API validation"
  → Available in future sessions

Example 3: GitHub Integration

With github MCP enabled:

User: "Create an issue for the login bug we discussed"

Claude: [Uses github MCP]
  → Creates issue with title, body, labels
  → Links to relevant code
  → Assigns to team member if specified

Memory MCP Deep Dive

The Memory MCP deserves special attention as it enables persistent project knowledge.

Memory Commands

# Built-in skills for memory management
/memory-save    # Save important knowledge
/memory-search  # Search saved knowledge
/memory-list    # List all entities
/memory-audit   # Check memory health

Memory Structure

{
  "entities": [
    {
      "name": "Authentication System",
      "type": "Architecture",
      "observations": [
        "Uses JWT with 24-hour expiration",
        "Refresh tokens stored in httpOnly cookies",
        "Located in src/lib/auth.ts"
      ]
    },
    {
      "name": "Database Schema",
      "type": "Infrastructure",
      "observations": [
        "PostgreSQL with Prisma ORM",
        "Users table has email_verified column",
        "Soft deletes using deleted_at"
      ]
    }
  ],
  "relations": [
    {
      "from": "Authentication System",
      "to": "Database Schema",
      "type": "uses"
    }
  ]
}

Best Practices for Memory

## What to Save
✅ Architecture decisions and rationale
✅ Code patterns and conventions
✅ Bug fixes and their root causes
✅ Important configuration details
✅ Team decisions and constraints

## What NOT to Save
❌ Temporary debugging info
❌ One-time implementation details
❌ Information already in CLAUDE.md
❌ Frequently changing data

Troubleshooting MCP

Server Not Loading

# Check if server is registered
claude mcp list

# Verify settings file
cat .claude/settings.json

# Reset and re-add
claude mcp reset-project-choices
claude mcp add --scope project <name> -- <command>

Permission Issues

Ensure enableAllProjectMcpServers: true in project settings:

{
  "enableAllProjectMcpServers": true,
  "mcpServers": { ... }
}

Environment Variable Issues

Use ${VAR_NAME} syntax for environment variables:

{
  "env": {
    "DATABASE_URL": "${DATABASE_URL}"
  }
}

Or provide directly with -e flag:

claude mcp add --scope project postgres \
  -e DATABASE_URL="postgresql://..." \
  -- npx -y @modelcontextprotocol/server-postgres

Enterprise MCP Management

For enterprise environments, use the allowlist to control which MCP servers can be used:

// /etc/claude-code/settings.json
{
  "mcpServers": {
    "allowlist": [
      "filesystem",
      "memory",
      "git"
    ]
  }
}

This prevents users from adding unauthorized MCP servers.

Creating Custom MCP Servers

You can create custom MCP servers for specialized needs. The protocol specification is at modelcontextprotocol.io.

Basic Structure

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server(
  { name: 'my-custom-mcp', version: '1.0.0' },
  { capabilities: { tools: {} } }
);

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

server.setRequestHandler('tools/call', async (request) => {
  // Handle tool calls
});

const transport = new StdioServerTransport();
await server.connect(transport);

MCP vs Other Tools

Feature	MCP	Built-in Tools	Hooks
External data access	✅ Primary purpose	❌ Limited	❌ No
Persistent storage	✅ Memory MCP	❌ Session only	❌ No
Custom integrations	✅ Extensible	❌ Fixed	✅ Via commands
Context cost	Variable	Included	Minimal
Setup complexity	Medium	None	Low

Getting Started with MCP

Today:

1. Add filesystem and memory MCP to your project
2. Use MEMORY_FILE_PATH for project isolation
3. Save one important decision to memory

This week:

1. Add database MCP if applicable
2. Configure GitHub MCP for issue tracking
3. Explore memory commands (/memory-*)

This month:

1. Optimize MCP selection for context efficiency
2. Create project-specific MCP configurations
3. Consider custom MCP for specialized needs

---

MCP transforms Claude Code from a standalone assistant into an integrated development platform. Choose your servers wisely and unlock Claude’s full potential.

Sources: Model Context Protocol, Claude Code Documentation, MCP Servers Repository