Sees
- Your IP address
- A hashed room ID, and stream IDs
- Encrypted connection offers
Never sees
- Messages, files, or state
@vdoninja/mcp
An MCP server that gives Claude Code, Codex, Cursor, or any MCP client a private room to message, send files to, and share state with other agents. Peer to peer over encrypted WebRTC, with no account and nothing to host. Or through an encrypted relay you run, when WebRTC can't connect.
npm i @vdoninja/mcp
install
npx vdon-mcp-install
registers with Claude Code + Codex
Scroll through a real session: two agents, two machines, and every hop in between.
planner calls vdo_connect and joins a room through the handshake server.reviewer joins the same room and asks for planner's stream.vdo_send: the request goes straight to the other agent.reviewer reads it with vdo_receive and replies the same way.Both agents pick the same path. There's no automatic switching yet.
A direct, DTLS-encrypted data channel between the two agents. Nothing to host. Fastest on a LAN.
"transport": "webrtc"Relays the encrypted channel so peers never see your IP. Still needs WebRTC on both ends.
"force_turn": trueFor machines or networks where WebRTC can't run. Long polling through a relay you host, encrypted with a shared room key.
"transport": "http"Every network path has other parties in it. Here is each one, when it is involved, and what it can and can't see.
force_turntransport: "http"password, VDO.Ninja's built-in key encrypts the handshake. That stops casual snooping but isn't a secret. For private work, pass your own password to vdo_connect; peers without it can't even find the room.Four controls, all optional, all set per session. Or install with --preset secure-full.
Encrypts the handshake and hashes your room name with a secret only your peers know.
HMAC-signed, bound to the room, expire after 10 minutes by default. Enforce them to reject anyone without one.
allow_peer_stream_ids limits which stream IDs can talk to you or send files.
Per-peer X25519 key agreement signs control and file messages with HMAC-SHA256. Require it and unsigned ones are dropped.
Profiles decide which tools your agent can see. Fewer tools means less context spent and fewer ways to go wrong.
vdo_connectJoin a room; optionally auto-view a peer.
vdo_sendSend JSON or text to one peer or all.
vdo_receivePoll messages and events. Waits up to 30 s.
vdo_statusLive status for one session.
vdo_list_sessionsEvery active session.
vdo_disconnectLeave the room and clean up.
vdo_capabilitiesVersion, profile, and features. Call it first.
vdo_sync_peersEach peer's handshake, auth, and capabilities.
vdo_sync_announceRe-announce now instead of waiting for the heartbeat.
vdo_file_send_pathStream a local file without loading it into context.
vdo_file_sendSend from base64 data.
vdo_file_transfersProgress, both directions.
vdo_file_resumePick up an interrupted send.
vdo_file_receiveRead a finished file as utf8, json, or base64.
vdo_file_saveWrite a finished file straight to disk.
vdo_state_setSet a shared key and broadcast it.
vdo_state_getRead one key or the whole snapshot.
vdo_state_syncPull or push a full snapshot after a reconnect.
Claude Code asks Codex to review a patch. The reply lands back in the same session, ready to act on.
Send logs, builds, and datasets agent to agent. Large files spool to disk and resume after drops.
One writer, a few reviewers, one decider, all in one short-lived room.
Agents keep status in shared keys and catch up with one sync after a reconnect.
An agent on your laptop works with one on a GPU box or a teammate's desktop. No VPN, no open ports.
Spin up a room for one job and disconnect when it's done. Nothing to provision or tear down.
A VPN connects machines. This connects agents. They solve different problems and work fine together.
| VDO.Ninja MCP | VPN overlay (e.g. Tailscale) | |
|---|---|---|
| Agent messages, files, shared state | Built in, as MCP tools | Build it yourself on top |
| Network reach between machines | None. Only what tools send | Full IP access |
| Per-agent permissions | Tool profiles, tokens, allowlists | Network ACLs |
| Accounts and setup | None. npm install | Account, client on every host |
| SSH, databases, internal web apps | Not supported | Yes |
| Lifetime | Per task. Rooms come and go | Always on |
Tools any MCP client can call: connect, send, files, state.
Keep an agent room running, with a local inbox and wake hooks.
View on GitHub Build your own @vdoninja/sdkWebRTC media and data channels, directly.
View on GitHubNode 18 or newer. Install in a folder that will stick around: the installer saves an absolute path.
Pulls in the MCP server, the VDO.Ninja SDK, and a Node WebRTC runtime. Relay-only machines can skip WebRTC with --omit=optional.
npm i @vdoninja/mcpAdds the server to Claude Code and Codex, whichever are on your PATH.
npx vdon-mcp-installAsk your agent to call this tool. If it answers, you're wired up.
vdo_capabilitiesThe installer runs claude mcp add for you. Default scope is local; use --claude-scope user to make it available everywhere.
npx vdon-mcp-install --claude-only
# least privilege: messaging only
npx vdon-mcp-install --claude-only --preset core
The installer runs codex mcp add with an absolute path to the server script.
npx vdon-mcp-install --codex-only
# remove it again
npx vdon-mcp-install --codex-only --uninstall
Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project). Use an absolute path.
{
"mcpServers": {
"vdo-ninja-mcp": {
"command": "node",
"args": ["/ABSOLUTE/PATH/node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js"],
"env": { "VDON_MCP_TOOL_PROFILE": "core" }
}
}
}
Add to .gemini/settings.json (project) or ~/.gemini/settings.json. Restart, then run /mcp to confirm.
{
"mcpServers": {
"vdo-ninja-mcp": {
"command": "node",
"args": ["/ABSOLUTE/PATH/node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js"],
"env": { "VDON_MCP_TOOL_PROFILE": "core" }
}
}
}
Add under mcp in opencode.json (project) or ~/.config/opencode/opencode.json.
{
"$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
}
}
}
Any client that launches local stdio servers needs the same three things: a command, the script path, and optional flags or env.
{
"command": "node",
"args": ["/ABSOLUTE/PATH/node_modules/@vdoninja/mcp/scripts/vdo-mcp-server.js",
"--tool-profile", "core"]
}
Remote client? See MCP over HTTP.
npx vdon-mcp-demo-message and npx vdon-mcp-demo-file run a full exchange on a local simulated network. Prefix with MCP_DEMO_FAKE=0 to use the real one.Two agents trading a short message should stay this easy. Around that, here's what's planned. None of it ships today.
Recognizable agent names, capabilities, and availability. Clear stages from queued to read to done.
Keep message identity across WebRTC, TURN, and relay, with P2P-only, relay-only, or automatic policies.
A browser room with microphone, camera, and screen. Interruptible speech. Recording off by default.
Requests, progress, artifacts, and cancellation, with an optional A2A adapter.
An MCP server that gives AI agents tools to message, send files to, and share state with other agents over VDO.Ninja's peer-to-peer WebRTC data channels.
No. Install the npm package and go. VDO.Ninja's free public handshake server introduces peers, then data flows directly between them. If you run your own handshake server, point host at it. The optional HTTP relay is the only piece you'd host yourself.
Yes. @vdoninja/mcp is MIT licensed and free to use. Its @vdoninja/sdk dependency is MPL-2.0.
No. Messages, files, and state travel over the WebRTC data channel, encrypted with DTLS, directly between peers. If a TURN relay is needed, it only forwards ciphertext. The handshake server helps peers find each other and never carries app data unless you explicitly allow fallback on a send.
Anything your agent reads becomes part of its context, like any other tool result. To keep large or sensitive files out of the model, use vdo_file_send_path and vdo_file_save: they stream from disk and to disk.
A room name is just a string, so a guessable one can collide. For anything private:
passwordenforce_join_tokenallow_peer_stream_idsOr install with --preset secure-full and set VDON_MCP_JOIN_TOKEN_SECRET.
No inbound ports and no tunnel. It isn't a VPN: peers can only exchange what the tools send. There is no shell, file system, or network access between machines.
Usually. WebRTC tries a direct path first and falls back to TURN relays. Some strict corporate networks and WSL setups block WebRTC's UDP traffic entirely; TURN helps, but it isn't a guaranteed bypass.
If WebRTC can't run or connect at all, both agents can switch to transport: "http" and talk through an encrypted relay you host. There's no automatic switching yet.
Direct connections have no server hop, so latency is just the network path between the two peers. Files move in 64 KB chunks (configurable from 1 KB to 256 KB) with a 64 MB default limit you can raise with file_max_bytes. Files of 4 MB or more spool to disk instead of memory.
No. ok: true means your side accepted the message for sending. The other agent still has to call vdo_receive and act on it. When it matters, ask for a reply: that's your receipt.
VDO.Ninja's guidance is about 80 peers per room. Rooms of 2 to 5 agents are the sweet spot; split bigger groups across rooms.
Sessions send a heartbeat every 15 seconds and reconnect with backoff, from 3 up to 30 seconds. File transfers resume from the last acknowledged chunk, and vdo_state_sync brings shared state back in line.
Not on a third-party server. Incoming events wait in memory in your local MCP server (up to 2,000 per session) until vdo_receive reads them. Large incoming files can spool to a local folder. Disconnect and the session is gone.
If you use the HTTP relay, it keeps encrypted events in memory for up to 5 minutes (at most 512 events or 8 MiB per room) so peers can catch up after a blip. Nothing goes to disk, and a restart clears it.
Any MCP client that runs local stdio servers: Claude Code, Codex, Cursor, Gemini CLI, OpenCode, and others. For clients that connect to remote MCP servers, there's also MCP over HTTP.
Not yet. Today it's messages, files, and shared state. Voice, camera, and screen sharing in the same private room are the planned direction.
ninja-p2p keeps agents in an always-on room with a local inbox. This package is a set of MCP tools an agent calls when it needs them. Same VDO.Ninja transport underneath.
npm i @vdoninja/mcp
npx vdon-mcp-install