Skip to main content

​
What is MCP?

Model Context Protocol (MCP) is Anthropic’s standard for connecting AI assistants to external tools and data sources. It enables agents to:
  • Query databases directly
  • Interact with APIs
  • Access file systems
  • Control browsers
  • Connect to any custom service

​
Configuration

​
Location

MCP servers are configured in .claude/settings.json: 
{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"],
      "env": {
        "API_KEY": "${API_KEY}"
      }
    }
  }
}

​
Global vs Project

LocationScope
~/.claude/settings.jsonAll projects (user-level)
project/.claude/settings.jsonSingle project

​
Common MCP Servers

​
Supabase

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase@latest"],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "${SUPABASE_ACCESS_TOKEN}"
      }
    }
  }
}
Tools provided:
  • list_projects, get_project
  • execute_sql, apply_migration
  • list_tables, list_extensions
  • deploy_edge_function

​
Chrome DevTools

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-chrome-devtools"]
    }
  }
}
Tools provided:
  • take_screenshot, take_snapshot
  • click, fill, navigate_page
  • evaluate_script
  • list_console_messages

​
Firecrawl (Web Scraping)

{
  "mcpServers": {
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "${FIRECRAWL_API_KEY}"
      }
    }
  }
}
Tools provided:
  • firecrawl_scrape - Extract page content
  • firecrawl_search - Search the web
  • firecrawl_map - Discover URLs on a site
  • firecrawl_crawl - Crawl multiple pages

​
Grafana

{
  "mcpServers": {
    "grafana": {
      "command": "npx",
      "args": ["-y", "@grafana/mcp-server"],
      "env": {
        "GRAFANA_URL": "${GRAFANA_URL}",
        "GRAFANA_API_KEY": "${GRAFANA_API_KEY}"
      }
    }
  }
}
Tools provided:
  • search_dashboards, get_dashboard_by_uid
  • query_prometheus, query_loki_logs
  • list_alert_rules, list_incidents

​
Context7 (Documentation)

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp-server"]
    }
  }
}
Tools provided:
  • resolve-library-id - Find library documentation
  • query-docs - Search library docs

​
Environment Variables

​
Reference Variables

Use ${VAR_NAME} syntax to reference environment variables: 
{
  "mcpServers": {
    "my-server": {
      "env": {
        "API_KEY": "${MY_API_KEY}",
        "API_URL": "${MY_API_URL}"
      }
    }
  }
}

​
Security Best Practices

  • Store secrets in .env (git-ignored)
  • Use ${VAR} references, not hardcoded values
  • Rotate API keys regularly
  • Use minimal required permissions
Never commit API keys in settings.json - always use environment variable references.

​
Custom MCP Servers

​
Building Your Own

Create a custom MCP server for your tools: 
// my-mcp-server/index.js
import { Server } from "@modelcontextprotocol/sdk/server";

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

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) => {
  if (request.params.name === "my_tool") {
    return { content: [{ type: "text", text: "Result!" }] };
  }
});

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

​
Registering Custom Servers

{
  "mcpServers": {
    "my-tools": {
      "command": "node",
      "args": ["./my-mcp-server/index.js"],
      "cwd": "/path/to/project"
    }
  }
}

​
Permissions

​
Tool Approval

Configure which MCP tools auto-approve in settings: 
{
  "permissions": {
    "allow": [
      "mcp__supabase__list_projects",
      "mcp__supabase__list_tables",
      "mcp__chrome-devtools__take_screenshot"
    ]
  }
}

​
Permission Patterns

{
  "permissions": {
    "allow": [
      "mcp__supabase__*",           // All supabase tools
      "mcp__chrome-devtools__take_*" // Screenshot tools only
    ]
  }
}

​
Debugging

​
Check Server Status

# List configured MCP servers
claude mcp list

# Check if server starts
npx -y @supabase/mcp-server-supabase@latest

​
Common Issues

IssueSolution
Server won’t startCheck command/args, verify package exists
Auth failureVerify env vars are set correctly
Tools not appearingCheck server implements tools/list
Timeout errorsIncrease timeout or check network

​
Verbose Logging

# Enable debug output
export MCP_DEBUG=1
claude

​
Squad Integration

​
Per-Squad MCP Servers

Different squads can have different MCP configurations: 
.agents/squads/
├── engineering/
│   └── .claude/settings.json  # Supabase, GitHub
├── website/
│   └── .claude/settings.json  # Chrome DevTools
└── intelligence/
    └── .claude/settings.json  # Firecrawl, Grafana

​
Agent-Specific Tools

# Agent: Database Admin

## MCP Requirements
- supabase: execute_sql, apply_migration, list_tables

## Instructions
Use Supabase MCP to manage database schemas...

​
Best Practices

  • Start with official MCP servers before building custom
  • Use project-level config for project-specific tools
  • Document required environment variables
  • Test MCP servers independently before integration
  • Limit tool permissions to minimum required

Secrets Management

Secure API keys for MCP servers

Hooks

Automate actions around tool calls