> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agents-squads.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Configuration

> Connect agents to external tools and services via Model Context Protocol

## 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`:

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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)

```json theme={null}
{
  "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

```json theme={null}
{
  "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)

```json theme={null}
{
  "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:

```json theme={null}
{
  "mcpServers": {
    "my-server": {
      "env": {
        "API_KEY": "${MY_API_KEY}",
        "API_URL": "${MY_API_URL}"
      }
    }
  }
}
```

### Security Best Practices

<Check>
  * Store secrets in `.env` (git-ignored)
  * Use `${VAR}` references, not hardcoded values
  * Rotate API keys regularly
  * Use minimal required permissions
</Check>

<Warning>
  **Never commit API keys** in settings.json - always use environment variable references.
</Warning>

## Custom MCP Servers

### Building Your Own

Create a custom MCP server for your tools:

```javascript theme={null}
// 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

```json theme={null}
{
  "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:

```json theme={null}
{
  "permissions": {
    "allow": [
      "mcp__supabase__list_projects",
      "mcp__supabase__list_tables",
      "mcp__chrome-devtools__take_screenshot"
    ]
  }
}
```

### Permission Patterns

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

## Debugging

### Check Server Status

```bash theme={null}
# 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

```bash theme={null}
# 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:

1. **User override** — `~/.claude/mcp-configs/{squad}.json`
2. **Generated from context** — `~/.claude/contexts/{squad}.mcp.json` (built from a squad's `context.mcp` list)
3. **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

```markdown theme={null}
# Agent: Database Admin

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

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

## Best Practices

<Check>
  * 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
</Check>

## Related

<CardGroup cols={2}>
  <Card title="Secrets Management" icon="key" href="/guides/secrets-management">
    Secure API keys for MCP servers
  </Card>

  <Card title="Hooks" icon="webhook" href="/guides/hooks">
    Automate actions around tool calls
  </Card>
</CardGroup>