Your agent has compute, memory, and context. What it doesn't have is a way to hand a file to a human — or to another machine. @perkoon/mcp fixes that with one config block: three native tools, P2P transfer over WebRTC, no API keys, no size limit, free.
This is the MCP doorway into the same engine behind our CLI integration and A2A endpoint. If your agent runs in Claude Code, Claude Desktop, Cursor, VS Code, or Windsurf, this is the shortest path.
Setup: One Config Block
Claude Code — add to your project's .mcp.json:
{
"mcpServers": {
"perkoon": {
"command": "npx",
"args": ["-y", "@perkoon/mcp"]
}
}
}Claude Desktop — same block in claude_desktop_config.json. Cursor, VS Code (Copilot), Windsurf — add an MCP server with command npx -y @perkoon/mcp. Restart the client. Your agent now has three new tools.
The Three Tools
send_file
Creates a session, waits for a receiver, transfers directly:
Agent: "Send the report to my colleague"
→ send_file({ file_path: "./quarterly-report.pdf" })
← Session code: K7MX4QPR9W2N
Share URL: https://perkoon.com/K7MX4QPR9W2N
Transfer complete! 4.2 MB in 1.3s (3.2 MB/s)Optional parameters: password to protect the transfer, timeout in seconds to wait for the receiver (default 300, max 3600). The human opens the share URL on any device — phone included — and the file streams to them.
receive_file
The other direction — your agent picks up files a human or another agent sent:
Agent: "Download from session K7MX4QPR9W2N"
→ receive_file({ session_code: "K7MX4QPR9W2N" })
← Saved to: ./received/quarterly-report.pdfcheck_session
Status without side effects: is the session live, has the receiver joined, did the transfer finish. Useful for agents orchestrating longer flows.
What's Actually Happening
The MCP server spawns the perkoon CLI under the hood, which handles all the WebRTC machinery — signaling, ICE negotiation, encryption, chunking. Perkoon's servers see session codes and connection metadata, never file bytes. The transfer is browser-grade end-to-end encryption between exactly two machines.
That architecture is why the answers to the usual questions are short: API key? None needed. Size limit? None exists. Cost? Free — nothing is stored, so there's nothing to bill.
Agent-to-Human, Agent-to-Agent
The two patterns this unlocks:
- Agent → human: your agent finishes a build, a report, a dataset —
send_file, and the human opens a link on whatever device they're holding. No shared drive, no email size limit, no "I'll Slack it to you in pieces." - Agent → agent: one agent sends, the other runs
receive_filewith the session code — CLI to CLI, MCP to MCP, or mixed. No human in the loop, no cloud bucket as a dead drop.
MCP vs CLI vs A2A: Pick Your Doorway
| Doorway | Best when | Docs |
|---|---|---|
| MCP | Your agent lives in an MCP client — native tools, no shelling out | npm: @perkoon/mcp ↗ |
| CLI | Scripts, CI/CD, any agent with a shell — perkoon send file.zip --json |
CLI guide |
| A2A | Agent frameworks that speak A2A — JSON-RPC session orchestration | A2A guide |
All three converge on the same direct WebRTC transfer. Full automation reference — JSON events, state API, ready-to-run Playwright scripts — lives at /automate.
Why We Built This
File transfer tooling assumes a human at both ends: a browser, a drag-and-drop, an inbox. Agents don't have inboxes. They have tool calls. Making the transfer layer agent-native — structured outputs, exit codes, no interactive auth — is the whole point, and making it P2P means there's no storage bill to pass on to you. The longer story is in why Perkoon exists.