Subscriptions and MCP

A subscription is a short-lived rule an agent creates for one task: “send me events from this source that match this filter, until this expires”. Matching happens when the event arrives, so the agent only ever pulls what it asked for.

Correlation

Many providers register one webhook URL for the whole account, so you can’t create a URL per task. Instead, use one source per app, and have the agent put a task ID into the request it makes (for example Stripe’s metadata.task_id, or a branch name). Set the source’s correlate path to that value, and subscribe with the matching correlation.

Create one

curl -X POST https://api.getensue.com/v1/agent/subscriptions \
  -H "authorization: Bearer $ENSUE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "source": "stripe-prod",
    "inbox": "billing-agent",
    "correlation": "t_42",
    "once": true,
    "ttl": 3600
  }'

Field	Meaning
filter	Same conditions as a flow filter
correlation	Match only events carrying this value
once / max_events	Stop after the first, or after N, matching events
ttl	Required. Subscriptions expire after at most 30 days
label	Your own task ID, shown in the dashboard

When a subscription ends, a pull for it returns right away with its status instead of waiting.

MCP server

Agents running in an MCP client can use the inbox without custom code. Connect to https://api.getensue.com/mcp with a workspace API key. A key can be limited to certain inboxes.

Tool	Does
wait_for_event	Subscribe once to a source and wait up to 30 seconds for its event
subscribe, unsubscribe, list_subscriptions	Longer-lived subscriptions
next_events, peek_events, claim_events	Pull from the inbox
ack_event, release_event, extend_lease	Close or keep a lease
get_raw_event	The full body when the envelope’s view was cut
list_sources, list_inboxes, create_source	Discover and register sources