Relay & MCP bridge

SmartChats runs in a browser or on a phone. The agents and terminals you want it to reach run on your own computer, behind NAT, with no public address. The browser can’t open a connection to them. The relay solves this: both sides dial out to it over WebSocket, and it routes frames between them.

Components

The open clients default to wss://relay.kind.computer, which runs smartchats-relay-cf. The Node relay’s README does not mark it superseded, but the Cloudflare relay is what every default points at.

  browser (SmartChats)                         your computer
  --------------------                         ------------------------------------
  /client socket  ---WSS--->  relay  <---WSS---  /bridge socket
                              (one DO           |
                               per user)        +-- smartchats-mcp-bridge  <-stdio->  coding agent
                                                |   (kind: agent, one per agent)
                                                |
                                                +-- smartchats-hub  <-MCP/HTTP->  agents A, B, C
                                                |   (kind: hub, hosts every agent session)
                                                |
                                                +-- bin/pty-bridge.mjs  <-pty->  CLI in a terminal
                                                    (kind: pty)

A bridge is anything on your computer that dials /bridge. A client is a browser that dials /client, lists the sessions, and subscribes to one at a time. Every bridge is a session with a session_id, kind (pty, agent or hub), label and model.

Auth and pairing

There is no separate pairing step. Both sides present a Firebase ID token for your SmartChats account, and the relay routes only between sockets of the same account.

1. The socket opens with ?token=<Firebase ID token>. The Worker verifies the RS256 signature, issuer, audience and expiry against Google’s public keys before the WebSocket upgrade completes. A missing or bad token gets a 401 and no socket.
2. The Worker forwards the upgrade to the Durable Object named by the token’s uid. Every socket for one user lands on the same object.
3. The first frame is bridge_hello (or client_hello). It registers the session and negotiates the protocol version.
4. The relay checks the token’s expiry on every frame and closes an expired socket with 1008. Bridges refresh the token every 50 minutes with bridge_reauth. A reauth that fails closes the socket with 1008. A valid token for a different uid also closes it (identity changed).

Bridges get their token through smartchats-cloud-client, from the credentials file that smartchats login writes (~/.smartchats-mcp/credentials.json).

Run the MCP bridge

Use the bridge on a machine without a hub (a remote VM, CI). Build it from the repo, then add it to your agent’s MCP config:

cd packages/smartchats-mcp-bridge && npm run build
smartchats login   # once, for the relay token

{
  "mcpServers": {
    "smartchats-patch-through": {
      "command": "node",
      "args": ["/path/to/smartchats/packages/smartchats-mcp-bridge/dist/index.js",
               "--label", "claude-code @ my-mac"]
    }
  }
}

Tools: send_message_to_user, wait_for_message, poll_messages, ask_user, respond_and_wait, list_peers, send_message_to_peer. They have the same names and result shapes as the hub’s tools. wait_for_message waits 30 s by default.

Limits

Relay limits are Worker variables in packages/smartchats-relay-cf/wrangler.jsonc.

Durable frames are buffered per session until acked: at most 500 frames and 24 h, oldest dropped first. A receiver remembers the last 1,000 ids to drop replayed repeats.

Protocol

Protocol v2 wraps every data frame in an envelope:

{
  "v": 2,
  "id": "01JB8Z...",
  "type": "agent_event",
  "ts": 1790520000000,
  "session_id": "agent-bridge-...",
  "corr": "01JB8Y...",
  "body": { "event": "message", "text": "Done: tests pass.", "status": "complete", "timestamp": 1790520000000 }
}

Versioning. A peer offers v: 2 in its hello. The relay answers bridge_registered or session_list with v: 2 if it speaks v2. A reply without v means v1, and the peer falls back to flat frames ({ type, ...fields }). A hello without v is a v1 peer and gets flat frames with no ids, acks or replay. The type names are the same in both versions.

Control frames stay flat:

{ "v": 2, "type": "ack", "ids": ["01JB8Z..."] }
{ "v": 2, "type": "resume", "session_id": "...", "after": "01JB8Z..." }

A receiver acks what it handled (up to 500 ids a frame). On reconnect it sends resume with the last id it saw, and the relay replays newer buffered frames. If frames were lost to the buffer limits, the relay sends pending_dropped { count, overflow, expired } first.

Main message types

peer_error codes: BAD_PEER_MESSAGE, PEER_SELF, PEER_NOT_FOUND (also for another user’s session, so nothing leaks), PEER_OFFLINE. The relay sets from_session_id and from_label on a delivered peer message from the sender’s registration, so they can’t be spoofed.

Message status values on agent_event are ack, update, blocked, complete and failed. waiting_on is { "type": "user" } or { "type": "agent", "label": "..." } and comes only with blocked.

Connect your own bridge

import { connectRelay, loadOrCreateBridgeId } from 'smartchats-relay-connect';
import { resolveConfig } from 'smartchats-cloud-client';
 
const relay = connectRelay({
  relayUrl: 'wss://relay.kind.computer',
  config: resolveConfig(),
  bridgeId: await loadOrCreateBridgeId(),
  tag: 'agent',
  protocol: 2,
  hello: { kind: 'agent', label: 'my-tool @ my-mac', model: 'none' },
});
 
relay.on('registered', ({ session_id }) => console.log('session', session_id));
relay.on('message', (msg, meta) => { /* msg is { type, ...body }, meta is { id, ts, session_id?, corr? } */ });
relay.sendFrame('agent_event', { event: 'message', text: 'hi', timestamp: Date.now() });

Without protocol: 2 the helper speaks v1. It reconnects with backoff from 1 s to 30 s and refreshes the token every 50 minutes. Pass getToken to use your own token source.

See also

• Hub
• MCP Server
• Architecture