Open-source MCP server · @vdoninja/mcp

Give your AI agents a private line.

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
Works with any MCP client that runs local servers
ClClaude Code CxCodex CuCursor GeGemini CLI OcOpenCode +Any stdio client
How it works

Follow one request across the wire.

Scroll through a real session: two agents, two machines, and every hop in between.

00Two agents on two machines. Neither can reach the other.
  1. Two agents on two machines. Neither can reach the other.
  2. One install registers the MCP server with Claude Code and Codex.
  3. planner calls vdo_connect and joins a room through the handshake server.
  4. reviewer joins the same room and asks for planner's stream.
  5. WebRTC opens a direct, encrypted channel. The handshake server steps out.
  6. vdo_send: the request goes straight to the other agent.
  7. reviewer reads it with vdo_receive and replies the same way.
  8. Files move in 64 KB chunks: hashed, acknowledged, resumable.
  9. Shared state merges on every peer. The higher clock wins.
Three ways to connect

Direct first. A relay when you need one.

Both agents pick the same path. There's no automatic switching yet.

WebRTC · default

A direct, DTLS-encrypted data channel between the two agents. Nothing to host. Fastest on a LAN.

"transport": "webrtc"

WebRTC through TURN

Relays the encrypted channel so peers never see your IP. Still needs WebRTC on both ends.

"force_turn": true

Your own HTTP relay

For machines or networks where WebRTC can't run. Long polling through a relay you host, encrypted with a shared room key.

"transport": "http"

Set up the HTTP relay

Transparency

Who sees what.

Every network path has other parties in it. Here is each one, when it is involved, and what it can and can't see.

Handshake serverwss.vdo.ninja
While peers find each other

Sees

  • Your IP address
  • A hashed room ID, and stream IDs
  • Encrypted connection offers

Never sees

  • Messages, files, or state
STUN serversGoogle · Cloudflare
During connection setup

Sees

  • Your public IP and port, to find a route

Never sees

  • Anything you send
TURN relayVDO.Ninja TURN
Only if a direct path fails, or with force_turn

Sees

  • Both peers' IPs
  • Encrypted packets

Never sees

  • Contents: DTLS is end to end
Your HTTP relayvdon-mcp-relay
Only with transport: "http"

Sees

  • Connection addresses
  • Opaque room IDs, timing, sizes

Never sees

  • The room key or plaintext (AES-256-GCM)
The other agentyour peer
Once connected

Sees

  • Everything you send it
  • Your IP, on direct connections

Never sees

  • Your files, shell, or network, unless a tool sends them
Your AI providermodel API
On every tool call

Sees

  • Tool calls and results your agent reads, like any MCP tool

Never sees

  • Files your agent moves disk to disk without reading them
The default handshake key is public. Without a 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.
App data stays off the WebSocket. Messages, files, and state only travel over the WebRTC data channel. Falling back through the handshake server is off unless you explicitly allow it on a send.

Lock it down when it matters

Four controls, all optional, all set per session. Or install with --preset secure-full.

Room password

Encrypts the handshake and hashes your room name with a secret only your peers know.

Join tokens

HMAC-signed, bound to the room, expire after 10 minutes by default. Enforce them to reject anyone without one.

Peer allowlist

allow_peer_stream_ids limits which stream IDs can talk to you or send files.

Session MAC

Per-peer X25519 key agreement signs control and file messages with HMAC-SHA256. Require it and unsigned ones are dropped.

18 tools, 4 profiles

A small surface. Load only the slice you need.

Profiles decide which tools your agent can see. Fewer tools means less context spent and fewer ways to go wrong.

All 18 tools. The default when no profile is set.

Session7

vdo_connect

Join a room; optionally auto-view a peer.

vdo_send

Send JSON or text to one peer or all.

vdo_receive

Poll messages and events. Waits up to 30 s.

vdo_status

Live status for one session.

vdo_list_sessions

Every active session.

vdo_disconnect

Leave the room and clean up.

vdo_capabilities

Version, profile, and features. Call it first.

Peer sync2

vdo_sync_peers

Each peer's handshake, auth, and capabilities.

vdo_sync_announce

Re-announce now instead of waiting for the heartbeat.

Files6

vdo_file_send_path

Stream a local file without loading it into context.

vdo_file_send

Send from base64 data.

vdo_file_transfers

Progress, both directions.

vdo_file_resume

Pick up an interrupted send.

vdo_file_receive

Read a finished file as utf8, json, or base64.

vdo_file_save

Write a finished file straight to disk.

Shared state3

vdo_state_set

Set a shared key and broadcast it.

vdo_state_get

Read one key or the whole snapshot.

vdo_state_sync

Pull or push a full snapshot after a reconnect.

Full tool reference with every argument

Use cases

What people wire up first.

Second opinion

Claude Code asks Codex to review a patch. The reply lands back in the same session, ready to act on.

Artifact hand-off

Send logs, builds, and datasets agent to agent. Large files spool to disk and resume after drops.

Reviewer panel

One writer, a few reviewers, one decider, all in one short-lived room.

Shared task board

Agents keep status in shared keys and catch up with one sync after a reconnect.

Across machines

An agent on your laptop works with one on a GPU box or a teammate's desktop. No VPN, no open ports.

A room per task

Spin up a room for one job and disconnect when it's done. Nothing to provision or tear down.

Honest comparison

Not a VPN. On purpose.

A VPN connects machines. This connects agents. They solve different problems and work fine together.

VDO.Ninja MCPVPN overlay (e.g. Tailscale)
Agent messages, files, shared stateBuilt in, as MCP toolsBuild it yourself on top
Network reach between machinesNone. Only what tools sendFull IP access
Per-agent permissionsTool profiles, tokens, allowlistsNetwork ACLs
Accounts and setupNone. npm installAccount, client on every host
SSH, databases, internal web appsNot supportedYes
LifetimePer task. Rooms come and goAlways on

Which VDO.Ninja package do I need?

Get started

Set up in a minute.

Node 18 or newer. Install in a folder that will stick around: the installer saves an absolute path.

01

Install

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/mcp
02

Register

Adds the server to Claude Code and Codex, whichever are on your PATH.

npx vdon-mcp-install
03

Say hello

Ask your agent to call this tool. If it answers, you're wired up.

vdo_capabilities

The 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
Want proof before wiring up agents? 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.
Where it's going

A private room for people and their agents.

Two agents trading a short message should stay this easy. Around that, here's what's planned. None of it ships today.

Planned

Presence and receipts

Recognizable agent names, capabilities, and availability. Clear stages from queued to read to done.

Planned

One conversation, any route

Keep message identity across WebRTC, TURN, and relay, with P2P-only, relay-only, or automatic policies.

Planned

Talk and show

A browser room with microphone, camera, and screen. Interruptible speech. Recording off by default.

Planned

Tasks with outcomes

Requests, progress, artifacts, and cancellation, with an optional A2A adapter.

Read the direction guide

FAQ

Questions.

What is this, in one sentence?

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.

Do I need an account, an API key, or my own server?

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.

Is it free?

Yes. @vdoninja/mcp is MIT licensed and free to use. Its @vdoninja/sdk dependency is MPL-2.0.

Can VDO.Ninja read what my agents send?

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.

Does my AI provider see what agents send each other?

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.

Could a stranger join my room?

A room name is just a string, so a guessable one can collide. For anything private:

  • use a unique room name and your own password
  • turn on join tokens with enforce_join_token
  • list the peers you expect in allow_peer_stream_ids

Or install with --preset secure-full and set VDON_MCP_JOIN_TOKEN_SECRET.

Does it open ports or expose my machine?

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.

Will it work behind firewalls and NAT?

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.

How fast is it, and how big can files be?

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.

Does a successful send mean the other agent got it?

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.

How many agents can share a room?

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.

What happens if the connection drops?

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.

Are messages stored anywhere?

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.

Which clients does it work with?

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.

Can I talk to an agent by voice, or show it my screen?

Not yet. Today it's messages, files, and shared state. Voice, camera, and screen sharing in the same private room are the planned direction.

How is it different from ninja-p2p?

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.

Give your agents a private line.

npm i @vdoninja/mcp
npx vdon-mcp-install
MIT licensed · Free · Peer to peer · Built on VDO.Ninja