Documentation

Overview

@vdoninja/mcp is a Model Context Protocol server. It gives AI agents in different apps, or on different computers, a private room where they can find each other, exchange messages, move files, and keep shared task state. By default those tool calls become VDO.Ninja SDK operations over WebRTC data channels. When WebRTC isn't available, an optional self-hosted HTTP relay carries the same traffic.

Which VDO.Ninja package?

Install

Requires Node.js 18 or newer. Install into a folder that will stay put: the installer registers an absolute path to the server script, so moving the folder later means re-running it.

npm i @vdoninja/mcp
npx vdon-mcp-install

This installs the server, @vdoninja/sdk, and a Node WebRTC runtime (@roamhq/wrtc, an optional dependency; skip it with --omit=optional on relay-only machines). The installer registers the server with Codex and Claude Code, whichever CLIs it finds on your PATH.

Installer options

Presets

Connect a client

Any MCP client that can launch a local stdio server works. Codex and Claude Code are automated; the others take a few lines of JSON. Use an absolute path to vdo-mcp-server.js if your client starts in a different folder.

npx vdon-mcp-install --claude-only
npx vdon-mcp-install --claude-only --claude-scope user

npx vdon-mcp-install --codex-only

{
  "mcpServers": {
    "vdo-ninja-mcp": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js"],
      "env": { "VDON_MCP_TOOL_PROFILE": "core" }
    }
  }
}

{
  "mcpServers": {
    "vdo-ninja-mcp": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js"],
      "env": { "VDON_MCP_TOOL_PROFILE": "core" }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "vdo-ninja-mcp": {
      "type": "local",
      "command": ["node", "/ABSOLUTE/PATH/node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js",
                  "--tool-profile", "core"],
      "enabled": true
    }
  }
}

{
  "command": "node",
  "args": ["/ABSOLUTE/PATH/node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js",
           "--tool-profile", "core"],
  "env": { "VDON_MCP_TOOL_PROFILE": "core" }
}

Check the wiring

Ask your agent to call vdo_capabilities. If you get back the server's limits and active profile, it's connected.

{ "name": "vdo_capabilities", "arguments": {} }

First conversation

Open two agent sessions, on one machine or two. Pick a room name nobody else will guess.

1. Agent A joins

{ "name": "vdo_connect", "arguments": { "room": "lab_7f3k2", "stream_id": "agent_a" } }

The result includes a session_id like vdo_3f1c…. Every other tool needs it.

2. Agent B joins and points at A

{ "name": "vdo_connect",
  "arguments": { "room": "lab_7f3k2", "stream_id": "agent_b", "target_stream_id": "agent_a" } }

3. Wait for the peer, then A sends

Call vdo_sync_peers on A until agent_b shows up. Then address it by stream ID:

{ "name": "vdo_send",
  "arguments": { "session_id": "<agent_a_session>", "target": "agent_b",
                 "data": { "type": "chat.message", "text": "hello from agent_a" } } }

ok: true means the transport accepted the message, not that B has read it. Ask B to reply when you need confirmation.

4. B receives

{ "name": "vdo_receive",
  "arguments": { "session_id": "<agent_b_session>", "wait_ms": 1000 } }

Expect a data_received event whose data is the object A sent. If you only see lifecycle events, call vdo_receive again: the channel may still be opening.

No agents handy?

Two scripts run the full exchange for you on a simulated local network, then exit with pass or fail:

npx vdon-mcp-demo-message
npx vdon-mcp-demo-file
# use the real network
MCP_DEMO_FAKE=0 npx vdon-mcp-demo-message
# real network, forced through TURN
MCP_DEMO_FAKE=0 MCP_DEMO_FORCE_TURN=1 npx vdon-mcp-demo-file

How it works

Each agent runs its own copy of the MCP server as a local process. The servers find each other through VDO.Ninja's handshake server, then open a WebRTC data channel between them. From then on, data goes peer to peer.

Step by step

1. Tool call. Your agent calls vdo_connect. The client passes it to the local server as JSON-RPC over stdio.
2. Handshake. The server opens a WebSocket to wss://wss.vdo.ninja and joins the room. The room name is hashed with the room password, and the WebRTC offer and ICE candidates are encrypted with it before they leave your machine. Stream IDs are sent as-is with a short hash suffix, so don't put anything sensitive in them.
3. Route discovery. WebRTC asks public STUN servers (Google, Cloudflare) for your public address and tries to connect directly. If that fails, it uses a VDO.Ninja TURN relay.
4. Data channel. A DTLS-encrypted, reliable, ordered data channel opens between the two servers.
5. Traffic. vdo_send, file chunks, and state updates go over that channel. Incoming data is queued locally until your agent calls vdo_receive.

Who sees what

Rooms and sessions

• Room: a meeting point. Everyone with the same room name and password can find each other. Stick to letters, numbers, and underscores.
• Stream ID: an agent's name in the room, like planner. Random if you omit it. Peers use it in target_stream_id and allowlists.
• Target stream: set target_stream_id to connect straight to one peer. That's the simplest, most reliable two-agent setup.
• Session: one vdo_connect call. Returns a session_id. One server can hold several sessions, in different rooms, at once.
• Addressing: pass a peer's stream ID (or its UUID from vdo_sync_peers) as target to reach one peer. Omit it to send to everyone connected.
• Transport: webrtc (default) or http for the relay. Everyone in a room must use the same one.

Two to five agents per room works best. VDO.Ninja's guidance is about 80 peers per room at most.

Events

vdo_receive returns everything that happened since the last call, oldest first. Pass wait_ms (up to 30,000) to wait for something to arrive. Up to 2,000 events are held per session; older ones are dropped first.

Errors

Failed tool calls return isError: true and this shape. validation_error means bad arguments or a tool outside the active profile; fix and retry.

{ "ok": false,
  "error": { "type": "validation_error", "message": "…", "tool": "vdo_send" } }

Tools

18 tools in four groups. The profile column shows the smallest profile that includes each one. required marks required arguments.

Session

Peer sync

Files

Shared state

File transfer

The data channel is already reliable and ordered. On top of that, file transfer adds its own checks so a bad chunk or a dropped connection never leaves you with a corrupt file.

• Integrity: every chunk and the whole file are checked with SHA-256.
• Resume: a transfer ID is tied to the sending peer and the exact file. Retrying the same file continues where it stopped; different content under the same ID is rejected.
• Memory: incoming files of 4 MB or more spool to disk. Prefer vdo_file_send_path and vdo_file_save for anything large.
• Limits: 64 MB per file by default (file_max_bytes). The server keeps the 12 most recent completed incoming files.

Shared state

A small key/value store every peer in the room keeps a copy of. Each write carries a clock (a counter that only goes up) and an actor (the writer's stream ID). When two copies disagree:

1. The higher clock wins.
2. On a tie, the alphabetically later actor wins.

Every peer applies the same rule, so they all end up with the same value without a server deciding. Good for task status, assignments, and small flags. Not a database: keep values small and keys under the 2,048 limit.

{ "name": "vdo_state_set",
  "arguments": { "session_id": "vdo_9a0e…", "key": "task.status", "value": "approved" } }

Configuration

Server-wide settings come from environment variables or CLI flags. Security settings here become defaults for every vdo_connect; per-call arguments override them.

VDON_MCP_TOOL_PROFILE=core npx vdon-mcp-server
npx vdon-mcp-server --tool-profile file --require-session-mac true

Started directly in a terminal, the server prints a short "Server running (stdio)" banner. Started by an MCP client, it stays quiet, which is normal.

Security

Out of the box, data is encrypted in transit but anyone who knows your room name can join. Add layers as the work gets more sensitive.

A locked-down room

{ "name": "vdo_connect",
  "arguments": {
    "room": "acme_release_q3",
    "stream_id": "planner",
    "password": "a-long-random-string",
    "join_token_secret": "shared-secret-from-your-vault",
    "enforce_join_token": true,
    "allow_peer_stream_ids": ["reviewer", "decider"],
    "require_session_mac": true } }

Networking

• Direct first. WebRTC tries a direct path, which is fastest on a LAN and often works across the internet through NAT.
• TURN fallback. If direct fails, traffic relays through VDO.Ninja TURN servers. Still end-to-end encrypted; a little more latency.
• Privacy mode. force_turn: true always relays, so peers never see your IP. Some networks connect less reliably this way.
• Hard blocks. Some corporate firewalls and WSL network setups block WebRTC's UDP traffic. TURN helps but isn't a guaranteed bypass.
• No WebRTC at all? Use the HTTP relay: plain HTTPS POST and long polling through a server you run.
• Not a tunnel. Only tool payloads cross the channel. No TCP, SSH, or port forwarding.
• Reconnects. Heartbeats every 15 s. On a drop the session rebuilds itself with backoff, re-joins, and re-announces. Make your message handlers safe to run twice.

HTTP relay

For machines that can't run the native WebRTC library, or networks that block it. Both agents join the same encrypted room through a relay you operate. Messages, files, and shared state use the same tools.

1. Run the relay

Node 18+, no native dependencies. Generate two secrets: an access token for the relay and a separate room key for the clients.

# run twice: once for the token, once for the room key
node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))"
VDON_RELAY_TOKEN=<token> npx vdon-mcp-relay
# listens on 127.0.0.1:8790 (VDON_RELAY_HOST / VDON_RELAY_PORT to change)

For other computers, put it behind an HTTPS reverse proxy: forward /v1/rooms/ unchanged, keep the Authorization header, disable caching, allow 768 KiB request bodies and 30-second responses. Remote clients must use HTTPS; plain HTTP is only accepted on loopback.

2. Point each MCP server at it

Machines that only use the relay can install without WebRTC: npm install @vdoninja/mcp --omit=optional.

{
  "command": "node",
  "args": ["/absolute/path/node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js"],
  "env": {
    "VDON_MCP_RELAY_URL": "https://relay.example.com",
    "VDON_MCP_RELAY_TOKEN": "<relay access token>",
    "VDON_MCP_RELAY_KEY": "<64 hex characters>"
  }
}

The relay only ever gets the access token. Keep the room key on the clients. vdo_connect also takes relay_url, relay_token, and relay_key, but environment variables keep secrets out of the agent's context.

3. Join and send

{ "name": "vdo_connect", "arguments": { "transport": "http", "room": "project_room", "stream_id": "planner" } }
{ "name": "vdo_connect", "arguments": { "transport": "http", "room": "project_room", "stream_id": "reviewer" } }
{ "name": "vdo_send", "arguments": { "session_id": "<planner-session>", "target": "reviewer", "data": { "text": "Please review the plan." } } }

What the results mean

Limits and privacy

• Encryption: AES-256-GCM, key derived from the shared room key. The relay sees addresses, opaque room IDs, timing, and sizes, never the key or plaintext.
• Shared key, shared access: anyone with the room key can read all of that room's traffic and claim any identity in it. A target picks delivery; it isn't a private channel. Use separate rooms for separate trust groups.
• No forward secrecy: a leaked key decrypts previously captured traffic. Rotate keys when membership changes. Prefer WebRTC when that matters.
• Replay, not storage: up to 512 events or 8 MiB per room for 5 minutes, 16 rooms per relay, memory only. Long polls return within 25 seconds.

MCP over HTTP

For AI clients that connect to remote MCP servers over HTTP instead of launching a local process. This changes how your client reaches the MCP server, not how agents reach each other. It's a different service from the HTTP relay.

VDON_MCP_HTTP_BEARER_TOKEN=change-me npx vdon-mcp-http
# listens on http://127.0.0.1:8787/mcp

The package also ships a Cloudflare Worker template (assets/cloudflare/worker-proxy.js) that forwards MCP requests to an upstream HTTP server. It doesn't run WebRTC itself.

Troubleshooting

Guides

Choose the task you want to complete. Each guide is also available in Markdown.

Setup and connections

Optional remote tools

Reference and direction

Testing

# fast product checks: conformance, server smoke, sync security
npm run test:mcp
# full engineering suite
npm run test:mcp:all
# live network diagnostics
node tests/live-turn-smoke.js
node tests/live-turn-soak.js
node tests/live-turn-matrix.js

Soak, matrix, and tuning knobs are covered in advanced diagnostics. See the tool contract for arguments and protocol limits.

Edit this page on GitHub · Found a mistake? Open an issue.