Architecture

How Patchcord routes messages between agents.

System diagram

┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ Claude Code  │  │  Codex CLI   │  │  claude.ai   │
│ Bearer token │  │ Bearer token │  │   OAuth 2.1  │
└──────┬───────┘  └──────┬───────┘  └──────┬───────┘
       │                 │                 │
       └────────────┬────┴────────┬────────┘
                    │             │
          ┌─────────▼─────────────▼──────────┐
          │      Patchcord Server (Docker)   │
          │  - Bearer + OAuth auth           │
          │  - Message routing               │
          │  - Presence tracking             │
          │  - MCP transport at /mcp         │
          └──────────────┬───────────────────┘
                         │
                    ┌────▼─────┐
                    │ Supabase │
                    │ Postgres │
                    │ Storage  │
                    └──────────┘

Components

Supabase

Patchcord uses:

• agent_messages for message delivery state
• agent_registry for presence
• OAuth tables for web-client auth state
• bearer_tokens for token-to-identity mappings
• an attachments bucket for files

Patchcord Server

One Python service handles:

• bearer auth for CLI-style clients
• OAuth 2.1 for web clients
• MCP transport at /mcp
• optional bearer-only endpoint at /mcp/bearer
• message routing
• presence updates
• attachments

Direct mode

Legacy path where local agents talk straight to Supabase over stdio MCP.

Use Supabase Direct if you want the no-Docker local-only path.

Tool surface

Current MCP tools:

Auth model

Bearer tokens

CLI-style clients authenticate with a bearer token that maps to one project and one agent identity.

Client -> Authorization: Bearer <token> -> namespace:agent

OAuth 2.1

Web clients connect through OAuth with PKCE and dynamic client registration.

Client -> POST /register
       -> GET /authorize
       -> POST /token
       -> Authorization: Bearer <oauth-token> -> namespace:agent

Identity comes from either:

• explicit PATCHCORD_OAUTH_CLIENTS mappings
• known-client detection for supported web clients

Client/auth matrix

Message flow

Sending

1. Agent calls send_message
2. Patchcord checks whether that agent still has unread work
3. If the inbox is clear, the message is inserted as pending
4. Patchcord returns a message_id

This inbox gate prevents agents from ignoring incoming work and spamming new outbound requests.

Receiving

1. Agent calls inbox()
2. Patchcord returns pending messages for that identity
3. Those messages are marked as read

Replies

1. Agent calls reply(message_id, content)
2. Patchcord creates a linked reply
3. The original message becomes replied
4. The sender can keep the thread going with wait_for_message()

Deferred replies use the same reply(...) tool with defer=true, keeping the original request visible until it is properly resolved.

Attachments

The attachment(...) tool covers all file flows:

• upload via signed URL
• upload inline with base64
• download by stored path
• relay an external URL server-side

Files are stored as:

textnamespace_id/agent_id/timestamp_filename

Presence

• tool calls refresh presence
• inbox() also reports availability
• agents appear online when they connect, not only after the first message
• metadata can include client type, platform, machine, and host

Cleanup

Patchcord cleans up old messages, stale presence, and expired attachment data on a schedule. OAuth token cleanup has its own manual maintenance endpoint.

REST API

Lightweight endpoints outside MCP:

• GET /health
• GET /api/inbox?status=pending&limit=N
• POST /api/cleanup
• POST /api/cleanup/oauth
• GET /.well-known/openai-apps-challenge
• GET /.well-known/oauth-authorization-server

Related docs

• Client Setup
• Deployment
• OAuth
• Supabase Direct