[effect-bot]

Closes EFF-3443

Chat turns can use MCP servers that anyone with Access configures on the chat sessions page. Attio's hosted server is the first one to add. The existing Attio Slack bot is unchanged.

Nothing is enabled by this PR. The table starts empty, so no turn gets a server until someone adds one and, for OAuth, connects it.

How it works

• Configuration is in Postgres, in chat_mcp_servers (migration 0060). Each server has a name (the mcp.<name>.<tool> prefix), an https URL, an authentication kind (none, bearer or oauth), Private (on by default) and Enabled. No secret is stored there.
• Credentials. Each server has its own Durable Object, McpCredential, named by its id. It holds either the bearer token or the OAuth client and refresh token.
  • Access tokens are refreshed one at a time across every session, while five minutes are still left.
  • A rotated refresh token is stored before the new access token is handed out.
  • A failed refresh waits 30 seconds before trying again.
  • invalid_grant or invalid_client shows the server as Needs consent until it's connected again.
• Connect (oauth) runs in the Worker:
  1. Discovery, using RFC 9728 resource metadata and then RFC 8414 server metadata.
  2. Dynamic client registration.
  3. PKCE S256 authorisation, with resource and the advertised scopes.
  4. The callback, /api/v1/chat/mcp-servers/:id/oauth/callback, which only accepts a state that hasn't been used and is under 10 minutes old.
• Turns.
  • Each turn reads the server list and gets every enabled server.
  • Private servers are offered only in Slack channels that hold no one from outside the workspace. That's PR Configure chat MCP servers from the dashboard #179's original conversations.info check, run once per session. A yes is kept, and a no or a failure is asked again next turn.
  • Discord and channels that couldn't be classified get only non-private servers. If the list can't be read, the turn gets no servers at all.
• Requests. Each MCP request gets its token from the server's credential inside the Worker. A 401 reports that token as rejected, so the next request gets a new one. The request that got the 401 is never retried. A server with no usable token doesn't connect for that turn.
• Dashboard. An MCP servers card next to the kill switch lists each server with its status. From it you can add a server (Private checked), switch Private and Enabled, set a bearer token, Connect, or delete. Deleting also wipes the credential.

A reviewer's path through the code

• packages/domain/src/Chat/McpServer.ts, packages/domain/src/Api/McpServers.ts: schemas, errors and endpoints.
• apps/cluster/src/Chat/McpCredential.ts: the credential (refresh, Connect, bearer, wipe), tested by McpCredential.test.ts. The OAuth protocol itself (discovery, registration, PKCE, client authentication, token requests) is the MCP SDK's helpers; this file keeps janitor's lifecycle: one refresh at a time, the 5-minute window, rotation stored before use, the 30-second backoff, needs-consent, the single-use 10-minute state, https-only endpoints and the generation fence that keeps a refresh or Connect callback from undoing a wipe or overwriting a newer credential.
• apps/cluster/src/Chat/McpCredentialObject.ts (the Durable Object) and McpCredentialClient.ts (the Worker's RPC side, which turns RPC failures into McpUnavailable, McpOAuthUnavailable or McpOAuthRefused).
• apps/cluster/src/Chat/McpServers.ts: choosing a turn's servers. McpFetch.ts is the fetch over the Worker's HttpClient that the SDK's transport and OAuth helpers share: the per-request token, the single refresh after a 401, the SDK's redirect: manual passed through so it can refuse cross-origin and https-to-http redirects, and, for the transport, failed responses without their body. McpServerStore.ts is the SQL.
• apps/cluster/src/Ingress/McpServers.ts: the API handlers.
• apps/cluster/src/Chat/Session.ts, Worker.ts: the wiring.
• apps/web/src/components/mcp-servers.ts: the panel, which chat-sessions.ts embeds next to the kill switch.

Refresh window cost

Tokens are refreshed once less than five minutes of them are left, as specified. A token that lives five minutes or less, or an answer without expires_in, which is treated as five minutes, is refreshed on every MCP request: one token request and one refresh-token rotation per request. Attio's real token lifetime hasn't been checked, because that needs a live token. If a provider issues tokens that short, the window should scale with the token's lifetime. docs/chat.md covers this.

Limitations (also in docs/chat.md)

• Every tool is offered, writes and deletes included, with no confirmation from janitor.
• Turns with MCP servers keep GitHub, Multica and internet access.
• Tool results show up in transcripts, which everyone with Access can read.
• The channel is checked once per session or thread, and guests aren't detected.
• A server that isn't private can be reached from public Discord channels.
• Anyone with Access can add a server that every thread can use.

Dependency upgrade

• clanka 0.18.2 to 0.22.2.
• Every Effect package to the pkg.pr.new snapshot of eff-698-cloudflare-cluster at 6e155f1c.
• Alchemy and every @alchemy.run/* package from the 55e34d0272 preview tarballs to npm 2.0.0-beta.85, which the new snapshot requires and which speaks state store protocol v8.
• Both Alchemy patches carried over to beta.85; none of their fixes is upstream yet.

Deploying: drain old sandboxes first

clanka 0.22.0 changed the executor RPC protocol, so a new Worker can't talk to a sandbox still running the old image. A chat session reuses its running sandbox whenever it passes the HTTP health check, for up to the 30-minute warm window (CHAT_SANDBOX_WARM_SECONDS). New chat sessions and new PR review runs always start on the new image.

1. Turn the chat kill switch on for every thread. Running turns stop within seconds, and released sandboxes start their 30-minute warm window.
2. Check the PR reviews page and deploy when no review is running. A review that starts or is caught mid-run during the deploy may fail and should be requested again.
3. Deploy.
4. Keep the kill switch on until Cloudflare confirms that every chat container started before the deploy is gone. Elapsed time is not the gate: 30 minutes after step 1 is when to start checking, not when to turn the switch off. A container still running from before the deploy keeps the switch on.
5. Turn the kill switch off.

A guest-version check in the sandbox health endpoint would remove these steps for future protocol changes; it's deferred.

Verification

• vp test run: 157 files, 1019 tests pass.

• vp check: 0 errors.

• workerd (workerd 1.20261026.1, offline, synthetic credentials). A harness ran McpCredential in a native Durable Object with real storage. Its RPC results used alchemy's encodeRpcError/ErrorTag envelope and were read back through alchemy's makeRpcStub with the declared error classes. Fake authorisation and MCP servers were the Worker's only outbound. All 15 checks pass on the final code:

  • tagged errors arrive as real classes;
  • tokens cross RPC as strings and are Redacted again;
  • Connect works end to end, and a replayed callback is refused;
  • storage holds only the client and refresh token;
  • five concurrent rejections over RPC cause one refresh;
  • the rotated refresh token is stored;
  • clanka's McpServers connects over the per-request fetch;
  • a 401 fails that one call with no retry, and the next call uses a new token;
  • wipe and bearer tokens work.

  Two probes with unsafe metadata, a javascript: authorisation endpoint and an http:// token endpoint, are both refused. A third probe, whose token endpoint answers 307 to another origin, sends nothing there on workerd's real fetch; before the redirect fix it did. The harness didn't go through alchemy's DurableObject.make bridge or the full Worker bundle, so the first development deploy should still be watched.

• No live MCP, OAuth or CRM calls, and nothing enabled.