10. MCP Protocol with GitHub OAuth for Claude.ai#

Status: Accepted

Supersedes: ADR 0004 — x-brain-key Header Auth

Context#

Claude.ai’s custom MCP connector now requires the MCP protocol (JSON-RPC over Streamable HTTP) and OAuth 2.1 authentication. The existing x-brain-key shared-secret header auth (ADR 0004) cannot participate in Claude.ai’s OAuth flow, so Claude.ai can no longer connect to the Supabase Edge Function directly.

A standalone MCP server is needed that speaks the MCP wire protocol and implements the OAuth 2.1 authorization code flow with PKCE (S256) that Claude.ai initiates.

Decision#

Deploy a standalone Python MCP server (open-brain-mcp) as a Kubernetes Deployment with its own Service and Ingress. The server uses GitHub as the OAuth authorization server — GitHub identity provides per-user authentication rather than a single shared key.

The existing Supabase Edge Function is retained for direct REST API access (e.g. from scripts or CLI tools that still use x-brain-key auth).

Key design choices:

  • GitHub OAuth App as the identity provider — reuses the same GitHub identity already used for cluster OAuth2 proxy and Cloudflare Access.

  • JWT session tokens issued by the MCP server after OAuth callback, validated on every MCP request.

  • Separate pod rather than sidecar or edge function rewrite — keeps the MCP protocol concerns isolated from the existing Supabase stack.

  • Direct database access — the MCP server connects to the Supabase PostgreSQL database internally, bypassing Kong/PostgREST for lower latency.

Consequences#

  • Claude.ai can connect via its native OAuth flow — no manual key copying

  • Per-user GitHub identity replaces the single shared secret for MCP access

  • Two auth mechanisms coexist: GitHub OAuth (MCP server) and x-brain-key (REST API) — adds surface area but serves different use cases

  • The MCP server is an additional pod to maintain and monitor

  • GitHub OAuth App must be created manually (Settings > Developer settings) with the correct callback URL

  • Key rotation is simpler for MCP (OAuth tokens expire) but x-brain-key rotation for the REST API remains a manual process