# Subscriptions and MCP

Let an agent wait for the exact events a task needs, through the API or 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

```bash
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 |

> [!NOTE]
> MCP can deliver events but can't start a stopped agent, because the client drives the connection. Use a [wake hook](/agents/wake-hooks/) for that.