Handoff: Send Files to Users & Agents

Handoff: File Sharing for AI Agents

Send a file from an AI agent to a user or another agent with a controlled share link: expiry, max opens, human approval, agent-only audience, revoke and access log. Remote MCP server + REST API, no human signup.

Handoff gives an agent a safe way to hand a file to someone else, either a human or another agent. One call (`share_file` over MCP, or `POST /v1/share`) returns a download link, with no API key needed. For more control, the agent saves the file privately, then creates a share link with the rules it needs: an expiry, a maximum number of opens, an optional human approval step, and a specific recipient agent. It can check status, revoke, and read the access log at any time.

• Remote MCP server: https://hand-off.space/mcp (Streamable HTTP)
• REST API: https://hand-off.space/v1 (OpenAPI, llms.txt)
• Auth: none for the first call. share_file / POST /v1/share without a key creates an account and returns its api_key once. Later calls send Authorization: Bearer (or pass api_key as a tool argument when the client can't set headers). You can also get a key on its own with signup / POST /v1/signup. No email, card or human account is needed.
• 14 MCP tools: share_file, signup, save_file, list_files, create_share_link, get_share_status, approve_share, deny_share, revoke_share, get_access_log, fetch_shared_file, delete_file, list_shares, update_share. initialize and tools/list need no key.
• Registry name: io.github.jueluddinsf/handoff

This repository holds docs and listing metadata. The service is hosted, so you have nothing to install.

Use it when an agent needs to…

• Deliver a report to a human. The agent saves report.pdf, then sends a link that expires in 24 hours and opens at most 3 times.
• Hand a file to another agent. The link works only when the named recipient agent presents its own key.
• Wait for a human before releasing a file. The link stays locked (pending_approval) until the owner approves it.
• Take something back. Revoke a link, and see every successful and refused open.

Common questions an agent asks

• How can my agent send a file (PDF, CSV, report, image) to the user? Call share_file with name and content_text (or content_base64), or POST /v1/share, and reply with the returned url. The user opens it in a browser. No account is needed to download.
• How do I get a temporary or expiring download link? Links from share_file expire in 7 days by default. Set expires_in_hours and max_opens on share_file or create_share_link. After that the link returns 410 expired or 429 limit.
• How do I transfer a file from one agent to another? Use audience: "agent" with the recipient's agent_id. Only that agent's key can open it, through fetch_shared_file or a plain GET.
• Can a human approve before the file is released? Yes. Set requires_approval: true. Opens are blocked until approve_share is called.
• Can I take a link back or see who opened it? Yes. Use revoke_share and get_access_log. Refused opens are logged too.
• Is it a public file host or a paste bin? No. Files are private by default and every link is an explicit grant you control.

Guides

• How an AI agent can send a file to a user: send a PDF, CSV or report as a link
• Temporary download link for AI agents: expiring, open-limited and revocable links
• Agent-to-agent file transfer over MCP: a link only one named agent can open
• Human approval before an agent releases a file: links stay locked until you approve

Quickstart: one call

REST, raw bytes. The response is the URL, plus api_key: hf_… on a second line when the call created an account:

curl -s --data-binary @report.pdf "https://hand-off.space/v1/share?name=report.pdf&format=url"

https://hand-off.space/g/…

api_key: hf_…

REST, JSON:

curl -s -X POST https://hand-off.space/v1/share -H 'content-type: application/json' \

-d '{"name":"notes.md","content_text":"# Notes","expires_in_hours":24,"max_opens":3}'

→ {"url":"https://hand-off.space/g/…","expires_at":"…","max_opens":3,"requires_approval":false,

"file_id":"…","grant_id":"…","token_prefix":"…","next":{…},"api_key":"hf_…"}

MCP. Connect to https://hand-off.space/mcp with no auth, then call:

{"name": "share_file", "arguments": {"name": "notes.md", "content_text": "# Notes"}}

The result has url, expires_at (7 days by default), grant_id, file_id and, for a new account, api_key once. Give the url to the recipient, who downloads with a plain GET. Save the `api_key`: you need it to revoke the link, check its status or read the access log. Send it as Authorization: Bearer (or as the api_key argument) on later calls, so new files stay in the same account.

share_file and POST /v1/share also take expires_in_hours, max_opens, audience (anyone_with_link or agent), audience_value, requires_approval, mime and an optional ref label. With raw bytes, pass them as query parameters.

More control: REST (3 calls)

Use this when you want to store a file once and create several links for it, each with its own rules.

BASE=https://hand-off.space

1. Sign up. The key is shown once, so store it.

curl -s -X POST $BASE/v1/signup -H 'content-type: application/json' -d '{"agent_id":"my-agent"}'

→ {"account_id":"…","api_key":"hf_…","agent_id":"my-agent","caps":{…},"next":…}

export HANDOFF_API_KEY=hf_...

2. Save a file privately (content_text, or content_base64 for binary)

curl -s -X POST $BASE/v1/files -H "authorization: Bearer $HANDOFF_API_KEY" -H 'content-type: application/json' \ -d '{"name":"report.md","mime":"text/markdown","content_text":"# Q3 report"}'

→ {"id":"FILE_ID","name":"report.md",…}

3. Create a share link

curl -s -X POST $BASE/v1/files/FILE_ID/grants -H "authorization: Bearer $HANDOFF_API_KEY" -H 'content-type: application/json' \ -d '{"audience":"anyone_with_link","expires_in_hours":24,"max_opens":3}'

→ {"grant_id":"…","url":"https://hand-off.space/g/…","token":"…","token_prefix":"…"}

More control: MCP (3 tool calls)

1. Connect your client to https://hand-off.space/mcp (configs below).
2. Get a key with the signup MCP tool (no key needed) or POST /v1/signup. Put it in your client's Authorization: Bearer … header and reconnect, or pass api_key on each call.
3. Call save_file → create_share_link, then hand over the returned url.

Tools

Every tool except share_file, signup and fetch_shared_file (on an anyone_with_link share) needs your API key. share_file with no key creates a new account.

Client configuration

You can connect with no header at all and call share_file, then save the api_key it returns. To add the key, replace YOUR_HANDOFF_API_KEY in the configs below with your key, or use the environment-variable form shown.

Claude Code

claude mcp add --transport http handoff https://hand-off.space/mcp \

--header "Authorization: Bearer YOUR_HANDOFF_API_KEY"

You can also commit a project-scoped .mcp.json, which is the file in this repo. Claude Code expands ${HANDOFF_API_KEY} from your environment:

{ "mcpServers": { "handoff": { "type": "http", "url": "https://hand-off.space/mcp",

"headers": { "Authorization": "Bearer ${HANDOFF_API_KEY}" } } } }

Claude Desktop

Claude Desktop custom connectors don't take a static header, so bridge with mcp-remote in claude_desktop_config.json:

{

"mcpServers": { "handoff": { "command": "npx", "args": ["-y", "mcp-remote", "https://hand-off.space/mcp", "--header", "Authorization:${HANDOFF_AUTH}"], "env": { "HANDOFF_AUTH": "Bearer YOUR_HANDOFF_API_KEY" } } } }

Cursor (~/.cursor/mcp.json or .cursor/mcp.json)

{

"mcpServers": { "handoff": { "url": "https://hand-off.space/mcp", "headers": { "Authorization": "Bearer ${env:HANDOFF_API_KEY}" } } } }

VS Code / GitHub Copilot (.vscode/mcp.json)

{

"inputs": [ { "type": "promptString", "id": "handoff_api_key", "description": "Handoff API key", "password": true } ], "servers": { "handoff": { "type": "http", "url": "https://hand-off.space/mcp", "headers": { "Authorization": "Bearer ${input:handoff_api_key}" } } } }

Cline (cline_mcp_settings.json)

Set "type": "streamableHttp" explicitly. If you leave it out, Cline falls back to legacy SSE.

{

"mcpServers": { "handoff": { "type": "streamableHttp", "url": "https://hand-off.space/mcp", "headers": { "Authorization": "Bearer YOUR_HANDOFF_API_KEY" }, "disabled": false, "autoApprove": [] } } }

Windsurf (~/.codeium/windsurf/mcp_config.json)

{

"mcpServers": { "handoff": { "serverUrl": "https://hand-off.space/mcp", "headers": { "Authorization": "Bearer ${env:HANDOFF_API_KEY}" } } } }

OpenAI Agents SDK (Python)

import asyncio, os

from agents import Agent, Runner from agents.mcp import MCPServerStreamableHttp

async def main(): async with MCPServerStreamableHttp( name="handoff", params={ "url": "https://hand-off.space/mcp", "headers": {"Authorization": f"Bearer {os.environ['HANDOFF_API_KEY']}"}, }, cache_tools_list=True, ) as handoff: agent = Agent( name="R