MCP Events
MCP Events lets an agent subscribe to your events through your MCP server. The agent calls events/subscribe on your MCP server with a callback URL. Your MCP server forwards the request to Outpost, which verifies the callback, stores the subscription and delivers matching events straight to the callback, signed with Standard Webhooks. Deliveries don't pass through your MCP server.
agent ──events/subscribe──▶ your MCP server ──POST /tenants/<TENANT_ID>/mcp/events/subscribe──▶ Outpost
agent ◀──────────── signed POST to the callback URL ──────────────────────────── Outpost
The spec defines the challenge, errors and rate limits. This page covers what you set up.
Enable MCP Events
Turn on MCP Events in Hookdeck MCP Events settings.
Set EXPERIMENTAL_MCP_ENABLED to true. Callback verification and insecure callbacks for development have their own options. See MCP Events configuration.
Define your events
Event definitions list the events agents can subscribe to and the arguments they can filter each one by. They use the format of an MCP events/list result:
{
"events": [
{
"name": "order.created",
"description": "A new order was placed.",
"inputSchema": {
"type": "object",
"properties": {
"status": { "type": "string", "enum": ["paid", "pending"] }
}
},
"payloadSchema": {
"type": "object",
"properties": {
"order_id": { "type": "string" },
"status": { "type": "string" },
"total": { "type": "number" }
}
}
}
]
}
An agent subscribing to order.created with {"status": "paid"} receives only the orders whose status is paid.
nameis a topic, unique in the list. WithTOPICSset, it must be one of them. Wildcards aren't allowed.payloadSchemais a required JSON Schema object that describes the event'sdata.inputSchemais an optional JSON Schema object that lists the arguments underproperties. Without it, every top-levelpayloadSchemaproperty that is a string, number, integer or boolean is an optional argument.- Each argument is a string, number, integer or boolean, and names a top-level field of the payload with a compatible type. Outpost delivers an event only if every argument equals the field of the same name.
description,deliveryand_metaare optional. Whendeliveryis set it must includewebhook.
Import the JSON (or YAML) in Hookdeck MCP Events settings, or edit the events there.
Set the JSON in EXPERIMENTAL_, inline or as the path of a JSON or YAML file.
If a definition is invalid, Outpost reports the event and the field, and still starts. MCP Events answers 503 until it is fixed. With no definitions, every subscription is refused.
Connect your MCP server
Your MCP server serves three MCP methods. For each one it calls Outpost with the Admin API key:
| MCP method | Outpost call |
|---|---|
events/list | GET /mcp/events/list |
events/subscribe | POST /tenants/<TENANT_ |
events/unsubscribe | POST /tenants/<TENANT_ |
For events/subscribe and events/unsubscribe, your MCP server:
- Resolves the tenant from its own authentication of the agent. The tenant ID in the path is the identity the subscription belongs to, and the agent never sends it. Outpost creates the tenant on first subscribe.
- Checks the permission. The spec requires the server to check that the caller may receive the event with those arguments. Outpost can't know your permissions.
- Forwards the request
paramsunchanged as the body. - Returns the response. A
200is the MCP result, to return as is. A422carries anmcp_errorwithcode,messageand, where the spec defines it,data, to return as the JSON-RPC error.
For example, for an agent that authenticated as the tenant acme:
curl -X POST 'https://api.outpost.hookdeck.com/2026-09-01/tenants/acme/mcp/events/subscribe' \
--header 'Authorization: Bearer <API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"name": "order.created",
"arguments": { "status": "paid" },
"delivery": {
"mode": "webhook",
"url": "https://agent.example.com/hooks/orders",
"secret": "whsec_C2FVsBQIhrscChlQIMV+b5sSYspob7oD"
},
"ttlMs": 3600000
}'
{
"resultType": "complete",
"id": "sub_3f9a1c2e7b4d4e6a8c0b5d1f2a3e4b6c",
"refreshBefore": "2026-11-12T13:00:00Z",
"cursor": null,
"truncated": false
}
Your MCP server returns that JSON as the result of events/subscribe. refreshBefore is the expiry Outpost granted, or null for none.
events/unsubscribe takes its own params (name, arguments and delivery.url) the same way and answers {"resultType": "complete"}.
events/list returns the events you defined, as an MCP events/list result. Pass the request's cursor and limit as query parameters; topics=a,b restricts the result to those events, for example to the events the tenant may see. It is a GET with no tenant.
The subscribe and unsubscribe calls answer 404 while MCP Events is off, and 503 while your event definitions are invalid or verification is temporarily unavailable. See the API reference for every request and response.
Reference
- Refresh. Subscribing again with the same tenant, event, arguments and callback URL refreshes the subscription: the same
id, a new expiry, and the newsecret, which signs alongside the old one for 24 hours. - Shared within a tenant. A subscription belongs to the tenant. Two agents on the same tenant that subscribe to the same event with the same arguments and callback URL share one subscription, and either can refresh or remove it. Give each user their own tenant if they shouldn't share.
- Lifetime. Outpost grants the
ttlMsyour MCP server forwards, exactly: omitted means 24 hours,nullmeans no expiry (refreshBeforeisnull), and0or less expires immediately. To enforce limits, such as a maximum lifetime, changettlMsbefore forwarding. An expired subscription receives no events. A no-expiry subscription lasts until it is unsubscribed or its tenant is deleted. A callback that keeps failing is auto-disabled when you turn on auto-disable (ALERT_), and a subscribe re-enables it.AUTO_ DISABLE_ DESTINATION - Topics and operator events. A subscription's event counts toward the tenant's
topics. A subscribe or unsubscribe that changes the tenant'stopicsemitstenant.subscription.updated. - Not a regular destination. The destinations API never returns subscriptions, and they don't count toward
MAX_or a tenant'sDESTINATIONS_ PER_ TENANT destinations_count. Only the subscribe endpoints manage them. - Attempts. Attempts and events for a subscription show
destination_typemcp, with the subscription'sidas the destination ID. See MCP Events Delivery for the delivery format, signing and retries.