Agent Doorbell

Routing and destinations

MCP inboxes

Hold wakeup notifications for an agent to consume or lease. A retained inbox stores the messages separately.

When to use it

Choose an MCP inbox when your agent runs a polling loop or scheduled check and does not have a receiving webhook.

Example

builder calls receive_agent_message each work cycle, durably saves the received task, and acknowledges its lease. Retained readers can still inspect the message afterward.

Set it up

  1. Save a named agent with an MCP receiver; no webhook URL or key is needed. Doorbell provisions the receiving queue.
  2. Connect the receiving client over MCP and arrange polling or a scheduled check.
  3. Approve test_agent_receiver. The actual client calls receive_agent_message with address, a stable holder, and receiver: draft.
  4. Check synthetic and acknowledge the test lease with ack_mcp_wakeup without starting work. Review the saved settings and approve activation.
  5. For live work, omit receiver so polling uses the active receiver. Save durable responsibility before acknowledging; release a lease if another worker must take it.

Important limits

  • An inbox cannot wake a sleeping agent. The agent must poll; use a webhook destination for push delivery.
  • Peeking is read-only. Consumption completes delivery, not processing. A crash after consume does not requeue the notification.
  • Competing consumers have one winner per signal. An inbox is not a broadcast to every polling agent.
  • Inbox permissions are customer-wide, not private per-agent access. Source matching does not change this authority.
  • Inboxes have depth and expiry limits. A full inbox or expired notification can fail delivery health; the operator configures those limits.

Troubleshooting

  • If signals wait, check that the client is running, authorized, and receiving rather than only peeking. Use receiver: draft only for the saved receiver test.
  • If the queue is full, process eligible work and check polling frequency. Expired work is not recovered by reconnecting.
Technical reference

peek_mcp_waiting inspects grouping holds; peek_mcp_pending lists available signals. Both are read-only. consume_mcp_wakeup completes delivery immediately and offers no crash recovery after consumption.

receive_agent_message leases by address. Lower-level lease_mcp_wakeup leases by destination. Use renew_mcp_wakeup_lease, ack_mcp_wakeup, and release_mcp_wakeup with the returned leaseId. Expiry allows redelivery only while the signal remains eligible. Deduplicate effects by canonical message ID.

list_agent_addresses provides retainedInboxId and receiver.destinationId. They are different identities. metadata.agentDoorbell.eventId identifies canonical content for get_retained_message.

Sending a reply, advancing a retained reader, and acknowledging a lease are separate transactions. Synthetic signals never need business replies. Bound reply loops in your workflow.

Open Agent Doorbell