MCP

VDO.Ninja MCP Skill

Use this skill to run VDO.Ninja as an MCP data bridge in Codex, Claude Code, and compatible MCP clients.

What It Is For

• Fast bot-to-bot data messaging.
• Reliable file send/receive over WebRTC data channels.
• Optional secure room membership and peer allowlists.

What It Is Not

• Not a generic TCP tunnel.
• Not guaranteed firewall bypass.

Core Transport Truth

• Transport is WebRTC data channels.
• TURN can improve success on restrictive networks.
• TURN is not guaranteed to bypass all enterprise policies.

Fast Path

1. Install MCP registration: npm i @vdoninja/mcp

2. Register for Codex/Claude: npx vdon-mcp-install

3. Start server: npx vdon-mcp-server If run directly in a terminal, it prints a short running banner and a first-call hint.

4. Optional least-privilege tool profile: VDON_MCP_TOOL_PROFILE=core|file|state|full npx vdon-mcp-server

5. First tool call: { "name": "vdo_capabilities", "arguments": {} }

Two Primary Workflows

Workflow A: Messaging

• Connect peer A and peer B with vdo_connect.
• Send with vdo_send.
• Receive with vdo_receive.
• Demo script: npm run mcp:demo:message

Workflow B: File Transfer

• Send with vdo_file_send or vdo_file_send_path.
• Track with vdo_file_transfers.
• Read with vdo_file_receive or persist with vdo_file_save.
• Resume interrupted send with vdo_file_resume.
• Demo script: npm run mcp:demo:file

Security Controls

• join_token + join_token_secret
• enforce_join_token
• allow_peer_stream_ids
• require_session_mac

For secure presets, set VDON_MCP_JOIN_TOKEN_SECRET before install/runtime. @vdoninja/mcp depends on @vdoninja/sdk, so SDK installs transitively.

AI Agent Contract

• Call vdo_capabilities first.
• Call vdo_connect before send/file/state tools.
• Prefer least-privilege tool profile.
• For files, use file tools instead of manual chunking via vdo_send.
• Handle validation_error and retry idempotently.

Testing

• Product test bar: npm run test:mcp
• Full engineering suite: npm run test:mcp:all
• Live diagnostics (optional): references/advanced-diagnostics.md

References

• Operator quickstart: references/quickstart-and-compat.md
• Client config examples: references/client-config-examples.md
• Tool contract: references/mcp-tool-contract.md
• Transport notes: references/vdo-ninja-p2p-data-notes.md
• Registry manifest: server.json