> ## Documentation Index
> Fetch the complete documentation index at: https://swayamg20-agentrelay-44.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
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.
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](https://modelcontextprotocol.io), 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=`) 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:
```json theme={null}
{
"id": "frank@acme",
"name": "Frank — Frontend",
"owner_email": "frank@acme.com",
"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](https://a2a-protocol.org):
| 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
How the four-layer trust model stops prompt-injected handoffs from causing damage
Step-by-step Docker deployment for your team
How AgentRelay maps to the Linux Foundation A2A spec
The full A2A JSON-RPC surface exposed by the relay