WebSocket protocol

The app holds one WebSocket to Relay per link. Frames are JSON text, one object per frame, each with a type. The protocol version is the integer protocol in hello; this page describes version 1.

wss://api.meslzy.com/relay/v1/socket

Lifecycle#

1. Open the socket and send hello within 10 seconds, or the socket is closed.
2. Relay checks the link token and the tools, stores the tool list on the link and answers ready.
3. Each tool call arrives as call. Answer each with result or error. Calls can overlap, and you can answer them in any order.
4. Keep the socket open. Relay pings it, and your WebSocket library answers on its own.
5. When the socket closes, reconnect with backoff unless the close code says not to.

Frames the app sends#

hello#

{  "type": "hello",  "protocol": 1,  "token": "lt_3Vd9xZr2Lm8Tn4Bw6Yc1Hs7Pf5Gj0A2U",  "app": {    "name": "Notes",    "version": "1.4.2"  },  "instructions": "Notes is the person's local notebook. Search it before answering questions about their notes.",  "tools": [    {      "name": "search_notes",      "description": "Full-text search of the person's notes",      "inputSchema": {        "type": "object",        "properties": {          "query": {            "type": "string"          }        },        "required": [          "query"        ]      },      "annotations": {        "readOnlyHint": true      }    }  ]}

A hello that breaks any rule gets an `error` frame saying what is wrong, then the socket closes with 4400. To change the tools, close the socket and connect again with a new hello.

Tools#

Each tool is an MCP tool definition. Relay passes every field to hosts unchanged and never renames or prefixes a tool: the connector's name in the host already tells apps apart.

result#

{  "type": "result",  "id": "c_9Fq2Lr7Vx4Tm1Nb8",  "content": [    {      "type": "text",      "text": "3 notes match: Q3 invoices, Invoice template, Unpaid invoices."    }  ],  "isError": false}

content and structuredContent together must be at most 128 KiB as JSON.

error#

{  "type": "error",  "id": "c_9Fq2Lr7Vx4Tm1Nb8",  "message": "database is locked"}

A short way to report a failed call. Relay returns it to the host as a result with isError: true and the message as its text, so write the message for the model to repeat to the person. The call counts like any other answer.

ping#

{"type":"ping"}{"type":"pong"}

Optional. Relay answers pong. Browser code cannot see WebSocket ping frames, so a web app that wants to notice a dead socket sends ping now and then and expects pong.

Link commands#

The person controls their own link from your app, with no account of their own. Send a command with an id of your choice; Relay answers with the same id.

{"type":"link.rotate","id":"r1"}{"type":"link.pause","id":"r2"}{"type":"link.resume","id":"r3"}{"type":"link.revoke","id":"r4"}

The dashboard offers the same actions for every link of the project. A rotate there sends link.rotated with the new URL to a connected app, and a pause or resume sends link.state, both with id: null, so the app never holds a dead URL or a stale paused flag. Handle these frames whenever they arrive, not only after a command.

Frames Relay sends#

ready#

The link is live: hosts can reach the app from now on. ready does not carry the MCP URL; the app has it from link creation.

{  "type": "ready",  "linkId": "0199c4e2-5b7a-7d31-8f2e-6a1c9b3d4e57",  "paused": false,  "limits": {    "callTimeoutSeconds": 180,    "resultMaxBytes": 131072  }}

call#

{  "type": "call",  "id": "c_9Fq2Lr7Vx4Tm1Nb8",  "tool": "search_notes",  "arguments": {    "query": "invoices"  },  "deadline": "2026-10-12T10:03:00.000Z"}

• arguments already match the tool's inputSchema.
• deadline is when Relay stops waiting, 180 seconds after it sent the call. An answer after the deadline is too late: the host has been told the app did not answer.
• Calls can overlap. At most 8 calls per link are in flight at once; Relay refuses more before they reach the app.
• Every call reaches the app before anything runs, so the app can show what is about to happen and ask the person first before a destructive tool.

cancel#

{  "type": "cancel",  "id": "c_9Fq2Lr7Vx4Tm1Nb8"}

The host cancelled the call, closed its connection, or the deadline passed. Stop the work if you can. No answer is needed, and an answer sent after cancel is not delivered.

error#

{  "type": "error",  "id": null,  "code": "invalid_message",  "message": "tools[2].inputSchema is not a valid JSON Schema"}

Relay answers a frame it cannot use with an error frame. id is the id of the frame it answers, or null.

Keep-alive#

• Relay sends a WebSocket ping every 30 seconds. Every WebSocket library answers it with a pong on its own.
• A socket that stays silent for 90 seconds is closed. Reconnect as below.
• Pings, pongs, ping frames and an open socket with no calls are free.

The newest socket wins#

A link has one live socket. When a new socket sends hello with the same link token, Relay closes the older one with 4001 and sends calls to the new one. Calls still in flight on the old socket end with an error for the host and are taken off the month's count. An app that restarts can therefore reconnect at once, before Relay notices the old socket is dead.

Close codes#

Reconnecting#

Reconnect on every close except 4401, 4403 and 4410, waiting 1 second at first and doubling up to 30 seconds, with random jitter. Reset the wait once ready arrives. A deploy of Relay closes every socket at once, and the jitter keeps apps from all reconnecting in the same second.

const FINAL_CODES = [4401, 4403, 4410];
let attempt = 0;
const connect = () => {  const socket = new WebSocket("wss://api.meslzy.com/relay/v1/socket");
  socket.onopen = () => sendHello(socket);
  socket.onmessage = (event) => {    const frame = JSON.parse(event.data);
    if (frame.type === "ready") {      attempt = 0;    }
    handle(socket, frame);  };
  socket.onclose = (event) => {    if (FINAL_CODES.includes(event.code)) {      return showLinkProblem(event.code);    }
    const seconds = Math.min(30, 1 * 2 ** attempt);
    attempt += 1;    setTimeout(connect, seconds * (0.5 + Math.random() / 2) * 1000);  };};
connect();