Create an inbox per agent
One API call gives you an MCP URL for the user and a private webhook URL for your backend.
Agent Relay · Wake API
Want to use our API for your own MCP?
You run the MCP and the mailbox. We deliver the nudge: the exact string you send lands in the agent's session and wakes it, even when idle. No polling, no burned tokens, and your data never passes through us.
i How it works
The agent connects once
The user adds the MCP URL next to yours. Under Agent Relay, the agent links its own session, so later nudges arrive in that session.
Your backend sends the nudge
POST the exact words the agent should see. It wakes, calls your MCP for the real content, and acks it there.
Think of it as a SYN, not the payload. The nudge says there is something for you and names the id. The agent fetches it, takes the lease, and confirms through your MCP, so delivery is acknowledged where your data lives. All Agent Relay ever stores is the nudge text.
ii The API
Create an inbox (one per user or agent)
curl -X POST https://agentrelay.com/cloud/api/v1/events-shim/shims
# → { "mcp_url": ".../t/esm_…/mcp",
# "webhook_urls": { "bearer": ".../h/esh_…/bearer", … },
# "manage_token": "esk_…" }Give your backend a sender key
curl -X PUT https://agentrelay.com/cloud/api/v1/events-shim/shims/current/secrets/bearer \
-H "Authorization: Bearer $MANAGE_TOKEN" \
-H 'Content-Type: application/json' -d '{}'
# → { "secret": "esb_…" } shown once; keep it with the user's recordHand the user one line
claude mcp add --transport http webhooks "$MCP_URL"
# then: "Watch for webhooks and tell me when one arrives."Send a nudge
# WEBHOOK_URL is the inbox's /bearer URL
curl -X POST "$WEBHOOK_URL" \
-H "Authorization: Bearer $NUDGE_SECRET" \
-H 'Content-Type: text/plain' \
-H 'Idempotency-Key: task_42' \
--data 'New task t_42 is waiting. Read it with get_task on the acme MCP, then ack it.'
# → 202 { "ok": true, "seq": 7, "wake": "forwarding" }Check delivery
curl https://agentrelay.com/cloud/api/v1/events-shim/shims/current -H "Authorization: Bearer $MANAGE_TOKEN"
# → { "agent": { "connected": true, "wake": "linked" },
# "events": [{ "seq": 7, "delivery": "woken" }, …] }Verbatim on authenticated URLs. A text/plain post to the bearer URL (or a GitHub, Stripe or Linear signed URL) is delivered as exactly that text, trimmed and cut at 6,000 characters, so you control the prompt. On signed provider URLs the body must be plain text, not a JSON event, since the signature does not cover Content-Type. Posts to the open URL are always wrapped and marked as untrusted, because anyone holding that URL can send them.
Once per key. Retries with the same Idempotency-Key wake the agent once.
Delivery states. Each nudge is woken (injected into the session), read (picked up through the MCP) or waiting. If a session isn't running Agent Relay, the agent falls back to a background wait_for_webhook call and still gets it within seconds.
iii Where it runs
Agent Relay Cloud. Use the endpoints above. You send a pointer, not customer data, which keeps the security review short.
Self-hosted. The same API ships in the open-source control plane. Turn on the events_shim feature and run it in your own AWS, GCP or Kubernetes with our Helm charts. The wake logic is the open-source @agent-relay/events-shim package, so you can also mount the tools inside your own MCP server. See the self-hosting docs.
Agents. It works with Claude Code, Codex, opencode and the other harnesses Agent Relay delivers to, whether they run locally or in your sandboxes. We maintain the quirks of each one so you don't have to.
iv Pricing
Priced by message volume, not seats: agents are programmatic, so per-seat pricing doesn't fit. Self-hosted installs add a platform fee for setup and support. Start small and the price follows your volume as it grows.