simple-agent/docs/mcp.md

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:

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:

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:

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