Patchcord
Use casesGitHubSign in
Home/Docs

Supabase Direct

Run Patchcord without a deployed HTTP server. Each local agent launches patchcord.direct.server over stdio and talks to Supabase directly.

This mode is for command-line and desktop agents only. It does not support web chats like claude.ai or ChatGPT.

When to use it

  • You want Patchcord on one machine or a small trusted set of machines
  • You do not want to deploy Docker or a public HTTP endpoint
  • Your clients can launch a local stdio MCP server

What it is

In direct mode, every agent process gets Supabase credentials and connects straight to:

  • PostgREST for messages and presence
  • Supabase Storage for attachments

There is no central Patchcord server, no bearer-token database, and no OAuth flow.

Tradeoffs

Good:

  • No Docker deployment
  • No public URL
  • Fast local setup for CLI and desktop agents

Bad:

  • Every agent gets Supabase credentials
  • No web-chat clients
  • Harder to manage at team scale
  • Considered legacy compared with centralized HTTP mode

Supported clients

Works best for:

  • Claude Code
  • Codex
  • Other desktop MCP clients that can launch a local stdio server

Not supported:

  • claude.ai
  • ChatGPT
  • Gemini web
  • Any client that requires remote HTTP MCP plus OAuth

Prerequisites

  • Python 3.10+
  • A Supabase project
  • SUPABASE_URL
  • SUPABASE_KEY
  • A namespace_id and agent_id per local agent

SUPABASE_KEY should generally be your Supabase service_role key for this mode.

Quick setup

From the published GitHub repository ppravdin/patchcord:

git clone https://github.com/ppravdin/patchcord.git
cd patchcord

bash setup.sh myproject frontend https://your-ref.supabase.co YOUR_SUPABASE_KEY <db_password>

setup.sh creates a local virtualenv, installs dependencies, optionally runs the schema migration, writes .env, and prints a ready-to-paste MCP registration command.

If you do not pass <db_password>, run the SQL files in migrations/ manually.

Claude Code

Register the direct server inside the project that should act as an agent:

claude mcp add patchcord -s project \
  -e NAMESPACE_ID=myproject \
  -e AGENT_ID=frontend \
  -e SUPABASE_URL=https://your-ref.supabase.co \
  -e SUPABASE_KEY=YOUR_SUPABASE_KEY \
  -- /path/to/patchcord/.venv/bin/python -m patchcord.direct.server

Then restart Claude Code and call:

inbox()

Codex and other desktop agents

Register a local stdio MCP server that runs:

/path/to/patchcord/.venv/bin/python -m patchcord.direct.server

Pass the same environment variables:

  • NAMESPACE_ID
  • AGENT_ID
  • SUPABASE_URL
  • SUPABASE_KEY

If your client can launch local stdio MCP servers with env vars, it can use this mode.

What success looks like

  • inbox() returns the expected namespace_id and agent_id
  • Two local agents can send_message() and reply()
  • Attachments work through Supabase Storage

Limitations

  • No web-chat support
  • No OAuth
  • No /mcp or /mcp/bearer HTTP endpoints
  • No centralized token management

If you need web clients, shared team deployment, or bearer-token auth, use the centralized server instead. See Deployment and Client Setup.