# MCP Runbook

## Scope

This runbook covers the MCP adapter exposed by `app.mcp_main`.

## Endpoint

- Streamable HTTP endpoint: `POST /mcp` (mounted under `app.mcp_main`)

When using Docker Compose:

- Base URL: `http://127.0.0.1:8001/mcp`

## Runtime modes

Local:

```bash
uv run uvicorn app.mcp_main:app --host 0.0.0.0 --port 8001
```

Docker Compose service:

- `personal-agent-mcp`

## Tool surface

Always enabled:

- `check_availability`

Optional mutation tools (disabled by default):

- `scan_mailbox`
- `list_unsubscribe_candidates`
- `execute_unsubscribe`

Enable optional tools with:

```bash
MCP_ENABLE_MUTATION_TOOLS=true
```

## Authorization and scope gates

MCP tools call the shared auth backend and read auth headers from request context.

Supported auth headers:

- `X-API-Key`
- `Authorization: Bearer ...`

Required scopes:

- `check_availability`: `availability:read`
- `scan_mailbox`: `mail:scan`
- `list_unsubscribe_candidates`: `unsubscribe:read`
- `execute_unsubscribe`: `unsubscribe:execute`

## Tool verification

Verify tool list from Python:

```bash
uv run python - <<'PY'
import asyncio
from app.mcp.server import mcp

async def main():
    tools = await mcp.list_tools()
    print([t.name for t in tools])

asyncio.run(main())
PY
```

Expected output by mode:

- default: `['check_availability']`
- with `MCP_ENABLE_MUTATION_TOOLS=true`: all four tools

## Protocol notes

- The server uses FastMCP Streamable HTTP.
- Basic GET to `/mcp` is not a health endpoint; MCP expects protocol-compliant requests.
- In local development, FastMCP may enforce host/origin checks. If you see `421 Misdirected Request`, verify host/port and reverse-proxy headers.

## Troubleshooting

If tools fail with auth errors:

- Check `AUTH_MODE` and credentials
- Confirm JWT contains required scopes
- For API key mode, verify `AGENT_API_KEY`

If tool calls fail with Google errors:

- Verify OAuth file mounts in Docker:
  - `GOOGLE_CLIENT_SECRETS_FILE`
  - `GOOGLE_TOKEN_FILE`