MCP Configuration

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

Location	Scope
`~/.claude/settings.json`	All projects (user-level)
`project/.claude/settings.json`	Single 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

Issue	Solution
Server won’t start	Check command/args, verify package exists
Auth failure	Verify env vars are set correctly
Tools not appearing	Check server implements tools/list
Timeout errors	Increase timeout or check network

Verbose Logging

# Enable debug output
export MCP_DEBUG=1
claude

Squad Integration

Per-Squad MCP Servers

squads-cli resolves each squad’s MCP config through a three-tier lookup, falling back to the next tier if the current one is missing:

User override — ~/.claude/mcp-configs/{squad}.json
Generated from context — ~/.claude/contexts/{squad}.mcp.json (built from a squad’s context.mcp list)
Fallback — your global ~/.claude.json

The CLI ships with an empty server registry by design — it prefers CLI tools (gh, gcloud, psql, …) over MCP wherever a good CLI alternative exists, and only reaches for MCP servers you explicitly configure.

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

Get Started

Core Concepts

Configuration

Building Agents

Governance

Production

Resources

API

What is MCP?

Configuration

Location

Global vs Project

Common MCP Servers

Supabase

Chrome DevTools

Firecrawl (Web Scraping)

Grafana

Context7 (Documentation)

Environment Variables

Reference Variables

Security Best Practices

Custom MCP Servers

Building Your Own

Registering Custom Servers

Permissions

Tool Approval

Permission Patterns

Debugging

Check Server Status

Common Issues

Verbose Logging

Squad Integration

Per-Squad MCP Servers

Agent-Specific Tools

Best Practices

Secrets Management

Hooks

​What is MCP?

​Configuration

​Location

​Global vs Project

​Common MCP Servers

​Supabase

​Chrome DevTools

​Firecrawl (Web Scraping)

​Grafana

​Context7 (Documentation)

​Environment Variables

​Reference Variables

​Security Best Practices

​Custom MCP Servers

​Building Your Own

​Registering Custom Servers

​Permissions

​Tool Approval

​Permission Patterns

​Debugging

​Check Server Status

​Common Issues

​Verbose Logging

​Squad Integration

​Per-Squad MCP Servers

​Agent-Specific Tools

​Best Practices

​Related

Secrets Management

Hooks

What is MCP?

Configuration

Location

Global vs Project

Common MCP Servers

Supabase

Chrome DevTools

Firecrawl (Web Scraping)

Grafana

Context7 (Documentation)

Environment Variables

Reference Variables

Security Best Practices

Custom MCP Servers

Building Your Own

Registering Custom Servers

Permissions

Tool Approval

Permission Patterns

Debugging

Check Server Status

Common Issues

Verbose Logging

Squad Integration

Per-Squad MCP Servers

Agent-Specific Tools

Best Practices

Related