Sources
MCP message sources
Let an authorized publisher send text and routing fields into Doorbell for routes to deliver to mailboxes.
When to use it
Agents send to each other through mailboxes with send permissions, with no source to set up. Create a custom MCP source only when publishers need a declared schema that routes can match.
Example
A research publisher sends Report ready with topic set to supplier_review. A route from that source admits the topic into the Supplier reviews mailbox, where the granted reviewer reads the text and fields.
Set it up
- For messages between agents, grant each agent its mailbox, approve recipients under Can send to, and call send_mailbox_message with at least one explicit recipient.
- For custom ingress, open Integrations > Sources and create an MCP message source with approved optional fields, such as topic. Message text is separate.
- In Mailboxes, select a mailbox and open Configure > Routes to add the custom source, with source-relative conditions such as topic equals supplier_review.
- Connect the publisher with messages:publish and publish using a stable retry key.
- Check inboxEntryCount and the mailbox separately from intentCount and trigger delivery.
Important limits
- This is a sending source, not a mailbox. An accepted custom publication can match no route; an ordinary mailbox send still requires an explicit permitted recipient.
- Custom source sender names are claims, not authenticated identities. Internal mailbox sends record the authenticated customer or agent as author separately from their sending mailbox.
- MCP publications and internal mail use the same immediate or fixed-batch timing and quiet hours as every other source.
- Accepted means durable acceptance, not destination delivery or completed work. Zero intentCount can coexist with mailbox entries, for example when a trigger is paused. routingOutcome describes notification intents, not mailbox admission.
- Changing routes does not replay past accepted messages. Identical retries with the same live source-scoped key return the original outcome for seven days; changing the content or correlation under that key conflicts.
- The managed doorbell-mailboxes source carries internal sends and cannot be selected by routes. An ordinary MCP source cannot impersonate its trusted identity or authenticated authors.
Troubleshooting
- If publication is refused, check messages:publish permission, source ID, source policy, message size, and the displayed customer-wide capacity. Follow any retry delay returned by Doorbell.
- For zero inboxEntryCount, inspect the routes from this source. For zero intentCount, inspect the mailbox's triggers, their conditions, and tested destinations.
- For a reply, set replyTo to an available canonical message ID. A conversation ID does not select a recipient. Bound reply loops in the workflow.
Technical reference
publish_mcp_message accepts sourceId, nonempty text, optional fields, a required idempotencyKey, and optional top-level conversationId and replyTo. The serialized publication JSON is limited to 256 KiB, including routing fields and JSON escaping.
Declare up to 20 optional string, number, or boolean fields, with paths up to three segments. Undeclared, missing, or wrong-typed values are omitted. Matching on text and declared fields is case-sensitive; all applicable conditions must match.
Version 2 receipts add messageId and inboxEntryCount to receiptId, acceptedAt, duplicate, intentCount, and routingOutcome. replyTo inherits its parent's conversationId; an explicitly different conversation conflicts. Let Doorbell generate the conversation ID for a new conversation.
{
"sourceId": "<your-source-id>",
"text": "Report ready",
"fields": {"topic": "supplier_review"},
"idempotencyKey": "report-42-ready"
}