MCP Agent Relay

Cross-machine agent communication for Claude Code over Tailscale.

Agents on different machines register, send messages, and coordinate tasks through a shared MCP server running on any Tailscale node.

Setup

pip install -r requirements.txt

Set a shared auth token:

export RELAY_AUTH_TOKEN="your-secret-token"

Start the server:

fastmcp run relay.py --transport http --port 8080

Expose via Tailscale

tailscale serve --bg 8080

This gives you a URL like https://your-hostname.tailnet-name.ts.net.

Add to Claude Code

Local (for testing):

claude mcp add --transport http relay http://localhost:8080/mcp \
  --header "Authorization: Bearer $RELAY_AUTH_TOKEN"

Over Tailscale:

claude mcp add --transport http relay https://your-hostname.tailnet-name.ts.net/mcp \
  --header "Authorization: Bearer $RELAY_AUTH_TOKEN"

Tools

Agent Discovery

• register_agent(name, capabilities) - Register and see who else is online
• list_agents() - List all registered agents
• heartbeat(name) - Stay online (5 min timeout)

Messaging

• send_message(from_agent, to_agent, content) - Direct message
• get_messages(agent_name) - Read and clear your inbox
• broadcast_message(from_agent, content) - Message all agents

Task Coordination

• create_task(title, description, created_by, assigned_to?) - Create shared task
• list_tasks(status?) - List tasks (all/pending/in_progress/completed)
• update_task(task_id, status?, assigned_to?) - Update task

Architecture

• Server: FastMCP 2.x, streamable HTTP transport
• Storage: SQLite with WAL mode (zero config, persistent)
• Auth: Bearer token via RELAY_AUTH_TOKEN env var
• Networking: tailscale serve handles HTTPS and DNS