Mercur
Try it free

Inspect a WebSocket session

A Mercur WebSocket endpoint forwards wss:// traffic to a port on your machine and records each public client as a Connection. Handshake headers, path, state, and data frames show up in the console the same way HTTP request history does for webhooks.

This page walks through create → forward → connect → inspect, then optional share and MCP. Guest mode and the free plan cannot create WebSocket endpoints. You need Solo or Team — see Pricing.

1. Create a WebSocket endpoint

Open Endpoints

Sign in, open Endpoints, and choose New Endpoint → WebSocket. Set Public access if anyone with the URL may connect, or restrict the address list.

The public host looks like this (your subdomain differs):

Example host
wss://your-endpoint.mercur.sh

WebSocket endpoints always forward. There is no log-only mode and no HTTP request log. Capture lives on the Connections tab.

2. Start the agent on the local port

Start the local WebSocket server first, then claim the endpoint with the macOS app or the npm CLI. Authenticated CLI tunnels need a workspace-scoped token — see CLI agent.

Run
mercur ws 4000

Replace 4000 with the port your process listens on. Leave that terminal open. One device holds the endpoint at a time.

3. Connect a client to the public URL

Point a WebSocket client at the printed wss:// URL, including path and query if your server expects them.

A default Socket.IO client starts with HTTP long-polling to /socket.io/, not a WebSocket upgrade. Polling must hit an HTTP endpoint. A WebSocket endpoint answers that GET with 503 No agent for client, and the browser often reports it as CORS. Details: Troubleshooting.

Check reachability with curl against the HTTP view of the same host (this is not a WebSocket handshake; it shows whether the relay has an HTTP agent):

Run
curl -i https://your-endpoint.mercur.sh/socket.io/?EIO=4&transport=polling

4. Inspect the Connections tab

Open the endpoint and switch to Connections. The list polls every few seconds; Refresh fetches immediately. Select a row for:

  • handshake path, query, and headers (truncated at 32 KB)
  • state: connecting, open, closed, or error
  • an event timeline: open, accept, message, close, error
  • text or binary payloads, truncated at 256 KB

Ping and pong are not stored. After 200 message events on one connection, later frames increment a dropped counter and are omitted. Lifecycle events (close, error) still persist.

Filters: path contains; grouped open/closed. There is no inject into a live socket and no Retry on WebSocket frames.

5. Share the session or read it from MCP

The share menu on the Connections tab issues a read-only link that lasts 24 hours. Anyone with the link can read connections for that endpoint. TCP endpoints cannot be shared.

On Solo and Team, a connected MCP client can read the same history. Typical flow: list_endpoints → list_connections → list_connection_events → get_connection_event. Event lists omit payloads; get_connection_event returns the stored frame. Setup: Remote MCP.

If it fails

Run curl -i on the public HTTPS URL before debugging the browser. A recorded WebSocket client that never completed Upgrade often has state: error on the Connections tab. A silent TCP reset with no HTTP status is the same class of failure as dropped WebSocket connections.

Stored connections follow the same retention window as HTTP logs: 30 days, then the oldest rows drop at the plan cap. See Limits and Security and data retention.

What a WebSocket inspector is not

  • No Socket.IO or GraphQL decoder — frames are stored as text or binary
  • No console send / inject into a live socket
  • No log-only WSS bin without an agent
  • No TCP connection inspector
  • Guest and Free stay HTTP-only

Related

Open Endpoints

Compare plans