Sources

MCP message sources

Let an authorized agent send text and routing fields into Doorbell for other workflows to receive.

When to use it

Use named send and reply tools for direct agent messages. Create a custom MCP source only when publishers need a declared schema that several agent inputs select.

Example

A research publisher sends Report ready with topic set to supplier_review. A supplier-reviewer address selects that source and topic, then receives the permitted text and fields.

Set it up

For direct messages, discover activated recipients with list_agent_addresses and use send_agent_message or reply_agent_message.
For custom ingress, open Sources and create an MCP message source with approved optional fields, such as topic. Message text is separate.
Select the custom source on a named agent, add source-relative conditions and shared fields, and save positive and negative samples.
Test the receiver and explicitly approve activation of the saved address.
Connect the publisher with messages:publish and publish using a stable retry key.
Check inboxEntryCount and retained history separately from intentCount and receiver delivery evidence.

Important limits

This is a sending source, not a receiving inbox. Retained inboxes store messages; MCP inbox destinations hold wakeup signals.
Agents with your customer-wide permissions are mutually trusted. Sender labels are claims, not authenticated per-agent identities; matching rules are not access controls.
MCP publications have independent notification timing. They bypass grouped-source waits, quiet periods, and cooldown without moving those windows.
Accepted means durable acceptance, not destination delivery or completed work. Zero intentCount can coexist with inbox membership, for example when a notifier is paused. routingOutcome describes notification intents, not inbox admission.
Changing rules does not replay past accepted messages. Identical retries with the same live key return the original outcome for seven days; changing the content or correlation under that key conflicts.

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 admission routes. For zero intentCount, inspect notifier activity, its inbox subscription, rule, and tested destination.
For a reply, set replyTo to an available canonical message ID and route the new message explicitly. 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. Use get_retained_message for canonical content and correlation. 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"
}

Open Agent Doorbell