relay-mcp

This repo is the open-source reference implementation. The author runs a private deployed instance at a different URL, but you should deploy your own instance for production use.

A self-hosted session relay for Claude. When you work across multiple Claude surfaces (Code, Cowork, Claude.ai connectors), each surface lives in its own context window. The relay gives them a shared message thread they can all post to and read from, so a Code session can hand state to a Chat session without copy-paste, and a scheduled Cowork task can leave a note your morning Chat picks up. It is a lightweight whiteboard, not a log or a memory store.

Tools

The server exposes six MCP tools.

Every message carries a surface field (chat, cowork, code, other) and an optional free-text session_tag so threads stay legible across many parallel sessions.

Architecture

• Cloudflare Worker at src/index.ts. Stateless. Speaks streamable HTTP MCP at /mcp.

• Supabase Postgres for thread, message, and read-cursor storage. Three tables, all prefixed relay_. RLS enabled with zero policies; only the Worker's service-role key can read or write.

• Two auth paths on the same server:

  • Static Bearer for Claude Code and Cowork: Authorization: Bearer <RELAY_API_KEY>. Simplest possible. No browser flow.
  • OAuth 2.1 with Dynamic Client Registration for Claude.ai custom connectors. The Worker exposes /.well-known/oauth-authorization-server, /register, /authorize, and /token. Access tokens are HS256 JWTs signed with RELAY_API_KEY. Stateless, no KV or Durable Objects required. Access tokens last 90 days, refresh tokens 365.

  See Security for the consolidated auth, rotation, and threat-model writeup.

• Single tenant in v1. The Worker reads a hardcoded user UUID from the RELAY_USER_ID secret. Multi-user support is a one-file change in src/oauth.ts plus an RLS policy migration; the schema already carries user_id columns.

Deploy your own

Self-hosting takes about ten minutes. You will need a Cloudflare account (Workers free tier is fine), a Supabase project, and Node 20+ locally.

1. Clone and install

git clone https://github.com/zhowe-designs/relay-mcp.git
cd relay-mcp
npm install

2. Create a Supabase project and run the migration

Create a new project at supabase.com. In the SQL editor, paste and run migrations/001_initial.sql. This creates relay_threads, relay_messages, relay_read_cursors, sets up indexes, enables RLS with zero policies, and revokes anon and authenticated grants.

From Project Settings → API, copy:

• The Project URL (looks like https://abcdef.supabase.co).
• The service_role key. Treat this like a database password.

3. Pick a tenant UUID

Generate one (uuidgen, crypto.randomUUID(), or any UUID v4 generator). This is the single user the v1 server is bound to. You can rotate it later, but everything posted under one UUID is invisible under another.

4. Set Worker secrets

npx wrangler login
npx wrangler secret put RELAY_API_KEY        # any random 32+ char string, your bearer
npx wrangler secret put SUPABASE_URL          # https://<project-ref>.supabase.co
npx wrangler secret put SUPABASE_SERVICE_KEY  # service_role key from step 2
npx wrangler secret put RELAY_USER_ID         # UUID from step 3

5. Deploy

npx wrangler deploy

Wrangler prints the deployed URL, something like https://relay-mcp.<your-subdomain>.workers.dev. That URL plus /mcp is the MCP endpoint.

6. Optional: custom domain

Edit wrangler.toml and uncomment the routes block, swapping relay-mcp.example.com for a hostname on a Cloudflare zone you own. Re-run npx wrangler deploy. Wrangler creates the CNAME automatically.

7. Smoke test

RELAY_URL=https://relay-mcp.<your-subdomain>.workers.dev RELAY_API_KEY=<your-key> \
  node --experimental-strip-types scripts/smoke.ts

Forty assertions, including the OAuth flow. All green means you are live.

Configure your clients

Replace <RELAY_URL> with your deployed URL and <RELAY_API_KEY> with the secret you set above.

Claude Code

Add to .mcp.json in the project root, or to ~/.claude.json for global access.

{
  "mcpServers": {
    "relay": {
      "type": "http",
      "url": "<RELAY_URL>/mcp",
      "headers": {
        "Authorization": "Bearer <RELAY_API_KEY>"
      }
    }
  }
}

Restart Claude Code, run /mcp, and confirm relay appears with six tools.

Cursor

Add to .cursor/mcp.json in the project root, or to ~/.cursor/mcp.json for global access.

{
  "mcpServers": {
    "relay": {
      "type": "http",
      "url": "<RELAY_URL>/mcp",
      "headers": {
        "Authorization": "Bearer <RELAY_API_KEY>"
      }
    }
  }
}

Restart Cursor, open the MCP settings, and confirm relay appears with six tools.

Gotcha: the relay block must sit inside the mcpServers object. Cursor silently ignores any server defined at the top level of the file. If the tools do not show up, this is the first thing to check.

Cowork scheduled tasks

Add an mcp_servers block to any task prompt that needs relay access.

mcp_servers:
  relay:
    type: http
    url: <RELAY_URL>/mcp
    headers:
      Authorization: "Bearer <RELAY_API_KEY>"

Claude Desktop

Claude Desktop's MCP support expects stdio commands, not remote HTTP URLs. To connect to a remote relay, use the mcp-remote bridge, which adapts a stdio-launched process to a remote HTTP MCP server.

Open claude_desktop_config.json (on Windows: %APPDATA%\Claude\claude_desktop_config.json; on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json) and add:

{
  "mcpServers": {
    "relay": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "<RELAY_URL>/mcp",
        "--header",
        "Authorization: Bearer <RELAY_API_KEY>"
      ]
    }
  }
}

Fully quit Claude Desktop (not just close the window) and reopen. The relay should appear in the tools menu with six tools.

Gotcha: Claude Desktop rewrites claude_desktop_config.json on some session lifecycle events and can silently wipe manual mcpServers additions. If your relay disappears between sessions, re-add the block and keep a backup copy somewhere outside the Claude Desktop config directory so you can paste it back. The Claude.ai custom connector path below avoids this entirely and is preferable if you can use it.

Claude.ai custom connector

Claude.ai uses OAuth 2.1 with Dynamic Client Registration, which the relay supports.

1. In Claude.ai, open Settings → Connectors → Add custom connector.
2. Name: anything, e.g. Relay.
3. Remote MCP server URL: <RELAY_URL>/mcp.
4. Leave the Advanced OAuth fields blank. Claude.ai handles registration automatically.
5. Click Add. A browser tab opens to your Worker's /authorize page.
6. Paste your RELAY_API_KEY into the single input and click Authorize.
7. The browser redirects back to Claude.ai. The connector lists six tools.

Access tokens last 90 days with automatic refresh, so you should rarely re-authorize. If auth ever fails, remove the connector and re-add.

Troubleshooting

Common failure modes from real deploys, with the first thing to check for each.

Smoke test fails with 401 Unauthorized. The RELAY_API_KEY in your local environment does not match the secret deployed to the Worker. Re-run npx wrangler secret put RELAY_API_KEY, then re-export the same value in the shell where you run the smoke test. Wrangler does not display secret values after they are set, so if in doubt, rotate to a fresh value on both sides.

Worker returns 5xx on any tool call. Almost always the Supabase service-role key was not set, or was set to the anon key by mistake. Re-run npx wrangler secret put SUPABASE_SERVICE_KEY with the value from Supabase Project Settings -> API -> service_role. Also confirm SUPABASE_URL is the project URL (no trailing /mcp, no path) and RELAY_USER_ID is a valid UUID v4.

Custom domain returns 530. Cloudflare 530 is a DNS resolution failure, usually the CNAME has not propagated yet. Wait a few minutes and retry. If it persists, confirm the hostname in wrangler.toml is on a Cloudflare zone you actually own and that npx wrangler deploy reported the route as attached.

Cursor does not see the relay tools. The relay block is sitting at the top level of .cursor/mcp.json instead of inside the mcpServers object. Cursor silently ignores top-level entries. Move the block inside mcpServers and restart Cursor.

Claude Desktop does not see the relay tools. Two likely causes. First, mcp-remote is missing or npx cannot fetch it on launch (Claude Desktop swallows stderr); run npx -y mcp-remote --help once in a terminal to prime the cache and surface any install errors. Second, Claude Desktop has overwritten claude_desktop_config.json and wiped your mcpServers entry; re-add it from your backup and fully quit and reopen the app.