Skip to main content

​
Overview

MCP (Model Context Protocol) servers extend Claude Code with external integrations like live documentation, browser automation, database access, and more. Configure servers at user, project, or agent scope.

​
Configuration Scopes

User Scope

~/.claude.json - Personal MCP servers available in all projects

Project Scope

.mcp.json - Team-shared servers for the project (requires approval)

Agent Scope

Agent frontmatter - Servers available only to specific agents

​
Basic Configuration

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"],
      "_comment": "Live documentation lookup. Eliminates outdated API guessing."
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-playwright"],
      "_comment": "Browser automation and E2E testing. Most token-efficient browser MCP."
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      },
      "_comment": "PRs, issues, code search. Essential for any GitHub-based project."
    }
  }
}

​
Server Definition Structure

​
command
string
required
Executable to run (e.g., npx, node, python, absolute path)
​
args
string[]
required
Command-line arguments passed to the executable
​
env
object
Environment variables for the MCP server processSupports variable substitution: ${VAR_NAME} reads from shell environment
​
_comment
string
Human-readable description (ignored by parser)

​
Approval Settings

Control how project MCP servers are authorized:
​
enableAllProjectMcpServers
boolean
default:"false"
Auto-approve all servers from .mcp.json
​
enabledMcpjsonServers
string[]
Allowlist of approved project MCP server names
​
disabledMcpjsonServers
string[]
Blocklist of denied project MCP server names
{
  "enableAllProjectMcpServers": true
}
Project MCP servers (.mcp.json) require explicit approval for security. User servers (~/.claude.json) are automatically trusted.

​
Permission Rules for MCP

Control MCP tool invocation using permission rules: 
{
  "permissions": {
    "allow": [
      "MCP(github:*)",
      "MCP(context7:*)",
      "MCP(playwright:navigate)",
      "MCP(playwright:screenshot)"
    ],
    "ask": [
      "MCP(github:push_files)",
      "MCP(playwright:click)"
    ],
    "deny": [
      "MCP(dangerous-server:*)"
    ]
  }
}
Pattern: MCP(server-name:tool-name)
  • MCP(github:*) - All tools from github server
  • MCP(*:*) - All MCP tools from any server
  • MCP(playwright:navigate) - Only the navigate tool

​
Daily Use

Servers recommended for everyday development:
Package: @upstash/context7-mcp@latestQuery live documentation from 100+ sources (React, Next.js, TypeScript, etc.) to eliminate API guessing.
{
  "context7": {
    "command": "npx",
    "args": ["-y", "@upstash/context7-mcp@latest"]
  }
}
Use cases:
  • Check latest API signatures
  • Verify deprecations
  • Find correct import paths
Package: @anthropic/mcp-playwrightE2E testing and browser automation. Token-efficient compared to other browser MCPs (~13.7k tokens avg).
{
  "playwright": {
    "command": "npx",
    "args": ["-y", "@anthropic/mcp-playwright"]
  }
}
Use cases:
  • Write E2E tests
  • Debug UI issues
  • Automate browser tasks
Package: @modelcontextprotocol/server-githubPRs, issues, code search, and repository management.
{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
    }
  }
}
Use cases:
  • Create and manage PRs
  • Search across repositories
  • Update issues and comments
Setup: Create a GitHub personal access token with repo scope and set GITHUB_TOKEN environment variable.

​
Add When Needed

Specialized servers for specific use cases:
ServerPackageUse Case
supabase@upstash/supabase-mcpDatabase operations (when using Supabase)
linear@linear/mcp-serverIssue tracking (when using Linear)
slack@modelcontextprotocol/server-slackTeam notifications (when using Slack)
filesystem@modelcontextprotocol/server-filesystemAdvanced file operations
postgres@modelcontextprotocol/server-postgresDirect PostgreSQL access
sqlite@modelcontextprotocol/server-sqliteSQLite database operations
Wisdom: Start with 3 MCPs (context7, playwright, github). Add only when you hit a concrete need. Most developers who start with 10+ end up using 3-4 daily.

​
Agent-Specific MCP Servers

Configure MCP servers that only specific agents can access: 
---
name: e2e-tester
description: Write and run end-to-end tests
tools: ["Read", "Write", "Bash", "MCP"]
mcpServers:
  playwright:
    command: npx
    args: ["-y", "@anthropic/mcp-playwright"]
---

You are an E2E testing specialist. Use Playwright MCP to automate browser tests.
  • Performance: Only load heavy MCPs when needed
  • Security: Restrict sensitive operations to specific agents
  • Context efficiency: Avoid polluting general agent context with specialized tools

​
Environment Variables

MCP servers often require credentials and configuration: 
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${DATABASE_URL}"
      }
    }
  }
}
Variable substitution: ${VAR_NAME} reads from your shell environment.
Never hardcode credentials in .mcp.json or settings.json. Always use environment variables and keep credentials in your shell profile or .env files (gitignored).

​
Custom MCP Servers

Run your own MCP server implementation: 
{
  "mcpServers": {
    "custom-api": {
      "command": "node",
      "args": ["/absolute/path/to/server.js"],
      "env": {
        "API_KEY": "${CUSTOM_API_KEY}"
      }
    }
  }
}

​
Debugging MCP Servers

If an MCP server isn’t working:
1

Check server availability

Test the command manually:
npx -y @upstash/context7-mcp@latest
2

Verify environment variables

Ensure required env vars are set:
echo $GITHUB_TOKEN
echo $DATABASE_URL
3

Review permissions

Check if MCP tools are allowed in your settings:
{
  "permissions": {
    "allow": ["MCP(server-name:*)"]
  }
}
4

Check approval status

For project servers, verify approval settings:
{
  "enabledMcpjsonServers": ["server-name"]
}
5

Use /doctor

Run the diagnostic command:
/doctor

​
Performance Considerations

​
Token Usage

MCP tools contribute to context usage:
ServerAvg Token ImpactNotes
context7Low (~2-5k)Fetches targeted docs
playwrightMedium (~14k)Includes browser state
githubMedium (~10-15k)Large API responses
filesystemLow (~1-3k)Depends on file size
postgresHigh (~20k+)Query results can be large
  • Request only needed data (use filters, limits)
  • Use context7 instead of loading entire docs
  • Clear context with /compact after heavy MCP operations
  • Consider agent-specific MCPs to isolate heavy tools

​
Startup Time

MCP servers add initialization overhead:
  • npx servers: ~2-5 seconds (download + start)
  • local binaries: ~100-500ms (start only)
  • Agent-specific: Only pay cost when agent spawns

​
Example Configurations

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-playwright"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  },
  "enableAllProjectMcpServers": false,
  "enabledMcpjsonServers": ["context7", "playwright", "github"]
}

​
Next Steps

Settings

Configure core Claude Code behavior

Permissions

Fine-tune MCP tool access control

Agent Configuration

Set up agent-specific MCP servers

Build docs developers (and LLMs) love

Get started for freeTalk to us