mcp-relay-client

Connect an agent to a session-based MCP relay — the protocol shipped by @particle-academy/agent-integrations. Point it at a relay session URL (the Add-to-Claude / share link from any app that mounts the relay — the Fancy UI Agent Playground or a site-wide co-browse session) and it speaks MCP to whatever app is hosting the session: list tools, call them, stream events, or bridge a real MCP client into the live browser surface.

Zero-install (npx) — recommended

No download, no install. The package is the bin:

npx -y mcp-relay-client <url> tools                 # list the host's tools
npx -y mcp-relay-client <url> call <name> '<json>'  # call a tool
npx -y mcp-relay-client <url>                        # stdio MCP bridge (no subcommand)

Mount a live browser session in your MCP client

Run with no subcommand and the CLI becomes a stdio MCP server that bridges your client to the relay session. Drop it into any MCP client config — Claude Code, Claude Desktop, Cursor — and the agent drives the live page directly (tools, results, and the host's notifications/agent_activity reverse channel all flow through):

{
  "mcpServers": {
    "fancy-session": {
      "command": "npx",
      "args": ["-y", "mcp-relay-client", "https://ui.particle.academy/?session=ABC&token=XYZ"]
    }
  }
}

Single-file clients (curl-and-run)

Prefer no Node? Each of these is self-contained, zero dependencies, and downloadable on its own:

| File | Runtime | Run | |---|---|---| | connect.sh | bash + curl | bash connect.sh <url> tools | | connect.py | Python 3.8+ | python3 connect.py <url> tools | | connect.ts | Node 22 / Bun / Deno / tsx | bun connect.ts <url> tools | | connect.go | Go | go run connect.go <url> tools |

# download just the one you want
curl -O https://raw.githubusercontent.com/Particle-Academy/mcp-relay-client/main/connect.sh

The connection URL (and the "inline key")

Pass whatever connection URL you were handed. The token (the inline key) may be embedded in the URL or supplied out-of-band via MCP_TOKEN. All of these work:

https://host/agent-playground?session=ABC&token=XYZ      # playground share URL
https://host/whiteboard-share/ABC?token=XYZ              # relay session URL
https://host/whiteboard-share/ABC/inbox?token=XYZ        # full inbox endpoint
https://host/whiteboard-share/ABC                        # + MCP_TOKEN=XYZ

The client derives the relay endpoints (…/<session>/inbox and …/<session>/events), the session id, and the token from the URL.

Commands

With the npx CLI (npx -y mcp-relay-client <url> …) or any single-file client (bash connect.sh <url> …):

<url>                          # (npx only) stdio MCP bridge — mount in an MCP client
<url> tools                    # initialize + list the host's tools
<url> call <name> ['<json>']    # call a tool (arguments default to {})
<url> send '<jsonrpc-frame>'    # send a raw JSON-RPC 2.0 frame
<url> watch                     # stream every frame the host emits

Example — drive the Agent Playground

URL='https://ui.particle.academy/agent-playground?session=ABC&token=XYZ'

bash connect.sh "$URL" tools
bash connect.sh "$URL" call screens_create '{"id":"board","kind":"whiteboard"}'
bash connect.sh "$URL" call screens_navigate '{"screen":"board"}'
bash connect.sh "$URL" call whiteboard_add_sticky '{"x":300,"y":200,"text":"hello from an agent","color":"#fde68a"}'

Environment

| Var | Flag (npx CLI) | Default | Meaning | |---|---|---|---| | MCP_TOKEN | --token <tok> | — | Token, if not inline in the URL. | | MCP_RELAY_PATH | --relay <path> | whiteboard-share | Relay mount path (apps that mount it elsewhere). | | MCP_INSECURE | --insecure | unset | Skip TLS verification (self-signed certs / local dev only). |

How it works

The relay is two HTTP endpoints, both token-gated:

• Send: POST {base}/{session}/inbox?token=… — a JSON-RPC frame, fanned out to the host's in-page MicroMcpServer.
• Receive: GET {base}/{session}/events?token=…&direction=outbound — an SSE stream of the host's response frames.

The client subscribes to the SSE stream, runs the MCP initialize handshake, then sends tools/list / tools/call and correlates responses by JSON-RPC id. The host renders; the agent drives — humans and agents share the same surface.

License

MIT © Particle Academy

⭐ Star Fancy UI

If this package is useful to you, a quick ⭐ on the repo really helps us build a better kit. Thank you!