How AgentRelay works: relay, MCP server, and A2A

AgentRelay uses two components: a local MCP server on each laptop and a team-hosted relay on Docker. Built on Hono, Postgres, and the A2A protocol.

AgentRelay splits the problem of cross-developer agent communication into two independent pieces: a tiny process that runs on each developer’s laptop, and a single service the team hosts together. The local piece speaks to your coding agent over stdio; the hosted piece stores handoffs, enforces identity, and notifies recipients. Neither half does anything useful without the other.

MCP server (agentrelay-mcp)

A local stdio process on each developer’s laptop. Runs as a child process of Claude Code or Codex CLI via the Model Context Protocol. Exposes seven tools to the agent. One per developer — nothing shared.

Relay service

One hosted service per team. Stores Agent Cards, handoff threads, and the inbox. Built on Hono, Drizzle, and Postgres. Deployed via Docker. All state lives here; the MCP server is stateless.

System diagram

The following diagram shows how a handoff travels from Bob’s agent to Frank’s agent:

┌──────────────────┐                                    ┌──────────────────┐
│  Bob's laptop    │                                    │  Frank's laptop  │
│  Claude Code     │     handoff (file diff, q…)        │  Claude Code     │
│   ↓ MCP stdio    │  ─────────────────────────────►    │   ↑ MCP stdio    │
│  agentrelay-mcp  │                                    │  agentrelay-mcp  │
└────────┬─────────┘                                    └────────┬─────────┘
         │  HTTPS / A2A JSON-RPC                                 │
         └─────────────────────┬───────────────┬─────────────────┘
                               ▼               ▼
                       ┌──────────────────────────────┐
                       │   Relay (one per team)       │
                       │   Hono + Drizzle + Postgres  │
                       │   Audit log, block list,     │
                       │   notification dispatcher    │
                       └──────────────┬───────────────┘
                                      ▼
                                  Slack DM

Both MCP servers communicate with the relay over HTTPS using the A2A JSON-RPC protocol. The relay is the only piece that handles cross-machine state; everything else is local.

Components

MCP server

The agentrelay-mcp package (on npm) is the local half. Claude Code and Codex CLI both speak the Model Context Protocol, so the same binary works for both clients. The MCP server connects to the relay using your developer API key and exposes these tools to your agent:

Tool	What it does
handoff_to_teammate	Package and send a handoff to a teammate
check_inbox	List your pending incoming handoffs
accept_handoff	Pull a handoff’s full context into the current session
send_message	Send a follow-up message in an existing handoff thread
complete_handoff	Close out a thread when the work is done
view_thread	Read the full conversation history for a thread
list_teammates	Discover registered teammates and their Agent Cards

The MCP server also enforces Layer 1 of the trust model: every inbound handoff is wrapped with a provenance preamble before your agent sees it, treating teammate content as data rather than instructions.

Relay

The relay is a stateless HTTP service backed by Postgres. It has four sub-components:

• A2A API server. Exposes the standard A2A JSON-RPC endpoints (message/send, tasks/get, tasks/list, tasks/update, tasks/cancel) plus system endpoints for registration and inbox listing.
• Agent Card registry. One row per developer. Cards are served at the A2A well-known URL (/.well-known/agent-card.json?id=<handle>) and describe each agent’s identity, skills, and repo ownership.
• Inbox store. An append-only log of handoffs and messages, indexed by recipient. The MCP server polls this via tasks/list.
• Notification dispatcher. Fires a Slack DM when a new handoff lands in someone’s inbox. Decoupled from the relay’s hot path, with email and desktop notifications planned for later versions.

Agent Cards

Each registered developer has an Agent Card — a JSON descriptor served from the relay. Cards follow the A2A spec and include identity, skills, and the developer’s relay endpoint:

{
  "id": "frank@acme",
  "name": "Frank — Frontend",
  "owner_email": "[e-mail]",
  "role": "frontend",
  "skills": ["react", "tailwind", "next.js"],
  "repos_owned": ["apps/web/", "packages/ui/"],
  "endpoint": "https://relay.acme.dev/agents/frank",
  "auth": { "type": "api_key" }
}

Because cards are standard A2A, any A2A-compliant agent — not just agentrelay-mcp — can look up teammates and send handoffs through the relay.

A2A protocol mapping

AgentRelay doesn’t invent a new protocol. Everything maps directly to the Linux Foundation A2A spec:

AgentRelay concept	A2A primitive
Handoff	A2A Task with role-tagged messages and artifact attachments
Message in a thread	A2A Message appended to a Task
Sending a handoff	message/send JSON-RPC method
Checking the inbox	tasks/list with a recipient filter
Pulling handoff context	tasks/get
Closing a handoff	tasks/update to status completed

This means third-party A2A-compliant agents can interact with an AgentRelay relay without any custom integration.

Handoff lifecycle

A handoff moves through three states from the moment it’s sent to the moment it’s resolved:

pending → accepted → completed

Pending: The handoff has been sent and stored in the recipient’s inbox. The relay fires a Slack DM. The recipient’s agent hasn’t pulled it yet.

Accepted: The recipient called accept_handoff. The full context — summary, artifacts, file diffs — is loaded into their session. Back-and-forth messages via send_message happen in this state.

Completed: Either side calls complete_handoff, which updates the A2A task status to completed. The thread is closed and the handoff falls out of the active inbox.

Notification flow

When a handoff lands in someone’s inbox, the relay’s notification dispatcher sends a Slack DM via an incoming webhook. The webhook URL is encrypted at rest with a key separate from the API key. This is the out-of-band signal that wakes the recipient up when their agent isn’t running — it’s not part of the handoff delivery itself, which happens through the A2A inbox polling.

Slack notifications are per-developer. Each teammate sets their own webhook URL through the relay’s admin tooling. Email and desktop notifications are planned for v0.2 and v0.3.

What AgentRelay is not

A few explicit non-goals help clarify what the system is designed for:

• Not real-time co-editing. AgentRelay moves tasks, not cursors.
• Not a Slack or Linear replacement. Notifications go through those tools, not against them.
• Not multi-org. One relay serves one team. v0.1 doesn’t span organizations.
• Not LLM-routed. The relay uses deterministic, rule-based routing. No LLM decides who gets a message.

Learn more

Trust model

How the four-layer trust model stops prompt-injected handoffs from causing damage

Deploy the relay

Step-by-step Docker deployment for your team

A2A protocol

How AgentRelay maps to the Linux Foundation A2A spec

API reference

The full A2A JSON-RPC surface exposed by the relay