[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_112":113},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":-5,"_41":42,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":-5,"_56":48,"_57":58,"_59":60,"_61":-5,"_62":-5,"_63":-5,"_64":-5,"_65":66,"_67":68,"_69":70,"_71":72,"_73":74,"_75":-5,"_76":-5,"_77":-5,"_78":48,"_79":-5,"_80":81,"_82":83,"_84":85,"_86":87,"_88":89,"_90":91,"_92":93},"apiUrl","https://odel.app/api","creator","zhowe-designs","moduleId","relay-mcp","@zhowe-designs/relay-mcp","displayName","relay mcp","tagline","Self-hosted session relay. Shared threads across Claude Code, Cowork, and Claude.ai.","iconKey","https://avatars.githubusercontent.com/u/247600891?v=4","category","local","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","pricingModel","free","creatorUserId","system:external-import","createdAt",1783399383000,"updatedAt",1788333294000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.zhowe-designs%2Frelay-mcp","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",1,"upstreamUpdatedAt",1780571064000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/zhowe-designs/relay-mcp","githubRepoFullName","zhowe-designs/relay-mcp","releaseId","ext-zhowe-designs-relay-mcp","version","0.1.0","descriptionMarkdown","# relay-mcp\n\n> 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.\n\nA 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.\n\n## Tools\n\nThe server exposes six MCP tools.\n\n| Tool | Description |\n|------|-------------|\n| `relay_list_threads` | List threads with last activity and message count. |\n| `relay_create_thread` | Create a named thread. |\n| `relay_post_message` | Post a message to a thread. Auto-creates the thread if missing. |\n| `relay_read_thread` | Read recent messages, newest first. Optional cursor update. |\n| `relay_check_new` | Return only messages since this reader last checked. |\n| `relay_archive_thread` | Soft-archive a thread. History is preserved. |\n\nEvery message carries a `surface` field (`chat`, `cowork`, `code`, `other`) and an optional free-text `session_tag` so threads stay legible across many parallel sessions.\n\n## Architecture\n\n- **Cloudflare Worker** at `src/index.ts`. Stateless. Speaks streamable HTTP MCP at `/mcp`.\n- **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.\n- **Two auth paths on the same server:**\n - **Static Bearer** for Claude Code and Cowork: `Authorization: Bearer `. Simplest possible. No browser flow.\n - **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.\n\n See [Security](#security) for the consolidated auth, rotation, and threat-model writeup.\n- **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.\n\n## Deploy your own\n\nSelf-hosting takes about ten minutes. You will need a Cloudflare account (Workers free tier is fine), a Supabase project, and Node 20+ locally.\n\n### 1. Clone and install\n\n```bash\ngit clone https://github.com/zhowe-designs/relay-mcp.git\ncd relay-mcp\nnpm install\n```\n\n### 2. Create a Supabase project and run the migration\n\nCreate a new project at [supabase.com](https://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.\n\nFrom **Project Settings → API**, copy:\n\n- The **Project URL** (looks like `https://abcdef.supabase.co`).\n- The **service_role** key. Treat this like a database password.\n\n### 3. Pick a tenant UUID\n\nGenerate 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.\n\n### 4. Set Worker secrets\n\n```bash\nnpx wrangler login\nnpx wrangler secret put RELAY_API_KEY # any random 32+ char string, your bearer\nnpx wrangler secret put SUPABASE_URL # https://.supabase.co\nnpx wrangler secret put SUPABASE_SERVICE_KEY # service_role key from step 2\nnpx wrangler secret put RELAY_USER_ID # UUID from step 3\n```\n\n### 5. Deploy\n\n```bash\nnpx wrangler deploy\n```\n\nWrangler prints the deployed URL, something like `https://relay-mcp..workers.dev`. That URL plus `/mcp` is the MCP endpoint.\n\n### 6. Optional: custom domain\n\nEdit `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.\n\n### 7. Smoke test\n\n```bash\nRELAY_URL=https://relay-mcp..workers.dev RELAY_API_KEY= \\\n node --experimental-strip-types scripts/smoke.ts\n```\n\nForty assertions, including the OAuth flow. All green means you are live.\n\n## Configure your clients\n\nReplace `` with your deployed URL and `` with the secret you set above.\n\n### Claude Code\n\nAdd to `.mcp.json` in the project root, or to `~/.claude.json` for global access.\n\n```json\n{\n \"mcpServers\": {\n \"relay\": {\n \"type\": \"http\",\n \"url\": \"/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer \"\n }\n }\n }\n}\n```\n\nRestart Claude Code, run `/mcp`, and confirm `relay` appears with six tools.\n\n### Cursor\n\nAdd to `.cursor/mcp.json` in the project root, or to `~/.cursor/mcp.json` for global access.\n\n```json\n{\n \"mcpServers\": {\n \"relay\": {\n \"type\": \"http\",\n \"url\": \"/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer \"\n }\n }\n }\n}\n```\n\nRestart Cursor, open the MCP settings, and confirm `relay` appears with six tools.\n\nGotcha: 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.\n\n### Cowork scheduled tasks\n\nAdd an `mcp_servers` block to any task prompt that needs relay access.\n\n```yaml\nmcp_servers:\n relay:\n type: http\n url: /mcp\n headers:\n Authorization: \"Bearer \"\n```\n\n### Claude Desktop\n\nClaude Desktop's MCP support expects stdio commands, not remote HTTP URLs. To connect to a remote relay, use the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge, which adapts a stdio-launched process to a remote HTTP MCP server.\n\nOpen `claude_desktop_config.json` (on Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`; on macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`) and add:\n\n```json\n{\n \"mcpServers\": {\n \"relay\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"mcp-remote\",\n \"/mcp\",\n \"--header\",\n \"Authorization: Bearer \"\n ]\n }\n }\n}\n```\n\nFully quit Claude Desktop (not just close the window) and reopen. The relay should appear in the tools menu with six tools.\n\nGotcha: 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.\n\n### Claude.ai custom connector\n\nClaude.ai uses OAuth 2.1 with Dynamic Client Registration, which the relay supports.\n\n1. In Claude.ai, open **Settings → Connectors → Add custom connector**.\n2. Name: anything, e.g. `Relay`.\n3. Remote MCP server URL: `/mcp`.\n4. Leave the Advanced OAuth fields blank. Claude.ai handles registration automatically.\n5. Click Add. A browser tab opens to your Worker's `/authorize` page.\n6. Paste your `RELAY_API_KEY` into the single input and click Authorize.\n7. The browser redirects back to Claude.ai. The connector lists six tools.\n\nAccess tokens last 90 days with automatic refresh, so you should rarely re-authorize. If auth ever fails, remove the connector and re-add.\n\n## Troubleshooting\n\nCommon failure modes from real deploys, with the first thing to check for each.\n\n**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.\n\n**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.\n\n**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.\n\n**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.\n\n**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.\n\n**OAuth flow on Claude.ai loops back to the authorize page.** The browser blocked third-party cookies on the Worker domain, or your `RELAY_API_KEY` was pasted with surrounding whitespace. Try a fresh browser profile, paste the key carefully, and watch the Worker logs (`npx wrangler tail`) for the actual error.\n\n## Usage\n\nOnce connected, you describe intent. The model picks the right tool. Some examples of sentences that work:\n\n- \"Post the last error, the migration diff, and my theory to relay thread `migration-debug`, surface code.\"\n- \"Read `daily-standup`, show me everything Cowork posted this morning.\"\n- \"Pull the last ten messages from `migration-debug`.\"\n\n### Thread naming\n\nShort, dash-separated, topic-scoped. `migration-debug`, not `april_migration_issues_2026`. One thread per topic, not one per day. Threads accumulate; conversations continue across weeks. A thread auto-creates the first time anything posts to it, so there is no ceremony around starting one.\n\nGood: `migration-debug`, `daily-standup`, `pricing-notes`, `scratch`.\n\nBad: `april-18-bugs`, `thread-1`, `general`.\n\n### Surface tagging is not optional\n\nAlways set `surface` to `chat`, `cowork`, `code`, or `other`. Six months from now when you scroll a thread, knowing a message came from a scheduled Cowork task versus a live Chat conversation changes how you weight it. Use `session_tag` for free-text grouping inside a surface (e.g. one tag per debugging session).\n\n### Archive dead threads\n\nWhen a topic is done, call `relay_archive_thread`. Archived threads hide from the default `list_threads` output but stay queryable via `include_archived`. Think Slack channels, not Git branches. Archive preserves history; it does not delete.\n\n### The boundary rule: transient layer, not canonical state\n\nThe relay is a conversation layer between sessions. It is not a log, not a decision record, and not a memory store. Anything you will care about next week belongs in your real system of record (decision log, task tracker, docs, code comments, etc.). The relay is what was said in the moment, not what was decided. If a relay post captures a real decision, write it down somewhere durable before moving on.\n\n### Never relay secrets\n\nSame rule as any chat. API keys, service-role tokens, OAuth secrets, database credentials. Those go in Wrangler secrets or your password manager. They never go in a relay message. The relay database is not a vault. See [Security](#security) for the full list of what not to post.\n\n## Security\n\nThis section consolidates the relay's auth model, key rotation procedure, content rules, and threat model.\n\n### Auth model\n\n**Static Bearer.** Claude Code and Cowork authenticate with `Authorization: Bearer `. The Worker compares the header to the `RELAY_API_KEY` secret on every request. There is no browser flow, no token exchange, no refresh. Whoever has the key has full access to every thread under the configured `RELAY_USER_ID`.\n\n**OAuth 2.1 with DCR.** Claude.ai custom connectors use OAuth 2.1 with Dynamic Client Registration against `/register`, `/authorize`, and `/token`. The user pastes their `RELAY_API_KEY` once into the Worker's authorize page; the Worker verifies it and issues an HS256 JWT signed with that same `RELAY_API_KEY`. Access tokens last 90 days, refresh tokens 365. No server-side session store, no KV, no Durable Objects.\n\n### Key rotation runbook\n\nRotate `RELAY_API_KEY` with:\n\n```bash\nnpx wrangler secret put RELAY_API_KEY\n```\n\nConsequences to plan for:\n\n- **All OAuth tokens are invalidated.** Tokens are JWTs signed with `RELAY_API_KEY`, so changing the secret breaks every existing signature. Every Claude.ai connector user must remove and re-add the connector and re-authorize with the new key.\n- **Static Bearer clients break until reconfigured.** Update `.mcp.json`, `.cursor/mcp.json`, `claude_desktop_config.json`, and any Cowork task `mcp_servers` blocks with the new key. Until each is updated, that client returns 401.\n\nRotate when a key is suspected exposed, when a teammate with access leaves, or on a routine schedule if your threat model calls for one.\n\n### What not to post\n\nThreads are persisted in Supabase and are visible to anyone holding the `RELAY_API_KEY`. Treat the relay as a shared whiteboard, not a vault. Do not post:\n\n- API keys, service-role tokens, OAuth client secrets, refresh tokens.\n- Database passwords or connection strings with embedded credentials.\n- Customer PII, regulated data, or anything covered by an NDA.\n- Anything that would be a problem if the relay backend, the Supabase project, or any client config holding the API key were compromised.\n\nSecrets belong in Wrangler secrets or a password manager. The relay database is not a vault.\n\n### Threat model\n\nThe relay is single-tenant in v1. It assumes the operator trusts every session that holds the `RELAY_API_KEY`, because any holder can read and write every thread under the configured `RELAY_USER_ID`. There is no per-session scoping, no audit trail beyond Worker logs, and no policy layer between the Worker and Supabase. Multi-user or multi-tenant deployments need additional auth layering (per-user keys, scoped tokens, RLS policies keyed off `user_id`) that is not provided here. The schema already carries `user_id` columns to make that extension straightforward, but you have to build it.\n\n## Development\n\n```bash\n# Typecheck\nnpm run typecheck\n\n# Local dev (requires .dev.vars, see .dev.vars.example)\nnpx wrangler dev\n\n# Smoke test\nRELAY_URL= RELAY_API_KEY= npm run smoke:remote\n\n# Rotate a secret (see Security for consequences)\nnpx wrangler secret put RELAY_API_KEY\n```\n\n## Schema\n\nThree tables, all prefixed `relay_`. Migration at `migrations/001_initial.sql`.\n\n- `relay_threads`. One row per named thread per user.\n- `relay_messages`. One row per posted message. Indexed on `(thread_id, created_at desc)`.\n- `relay_read_cursors`. One row per `(thread_id, reader_tag)`. Tracks \"last time this reader checked.\"\n\nService-role access only. RLS is enabled with zero policies, and `anon` and `authenticated` are revoked. Only the Worker's service-role key can read or write.\n\n## Layout\n\n```\nsrc/\n index.ts Worker entry, MCP JSON-RPC protocol, routes\n oauth.ts OAuth 2.1 facade (metadata, register, authorize, token)\n jwt.ts HS256 JWT sign, verify, PKCE check\n db.ts Supabase client factory\n types.ts\n tools/\n threads.ts list, create, archive, get_or_create\n messages.ts post, read, check_new\nmigrations/\n 001_initial.sql three tables + indexes + RLS lockdown\nscripts/\n smoke.ts end-to-end smoke test, includes OAuth\nwrangler.toml\npackage.json\nserver.json MCP Registry metadata\n```\n\n## Contributing\n\nThis is not an actively maintained community project. PRs are welcome for bugfixes, documentation improvements, and obvious quality-of-life additions. Larger features or refactors will likely be declined to keep the surface area small. Open an issue first if you want to discuss something nontrivial.\n\n## License\n\nMIT. See [LICENSE](https://github.com/zhowe-designs/relay-mcp/blob/master/LICENSE).\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"iconType","image","upstream",{"_100":101,"_102":103,"_104":105,"_106":107,"_108":-5,"_109":110},"requiredSecrets",[],"tags",[96,97,98,99],"assets",[],"stats",{"_94":81,"_95":81},"ratingAvg","reviewCount","claude","claude-code","cloudflare-workers","supabase","topics",[96,97,98,111,99],"license","MIT","language","TypeScript","registryName","io.github.zhowe-designs/relay-mcp","homepage","packages",[],"mcp","ENV",{"_114":115,"_116":117,"_118":119},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]