MCP Events
Let an agent subscribe to new EmitKit events and receive each one as a signed webhook.
MCP Events lets an agent subscribe to what happens in your product instead
of polling for it. The agent asks EmitKit’s MCP server for event.created,
optionally filtered by channel, tag or user. From then on EmitKit posts each
matching event to the agent’s callback URL as a signed
Standard Webhooks request.
It follows the MCP Events draft
with webhook delivery, on MCP protocol version 2026-07-28 and on the earlier
versions that use initialize, at the same endpoint as the tools:
https://api.emitkit.com/mcp
Before you start
- An OAuth connection or an API key for the Project the agent should hear about. Give the agent its own credentials. EmitKit doesn’t send an event back to the key or connection that created it (see No feedback loops), so an agent that shares your app’s key would miss your app’s events.
- A public
httpsURL that answers the verification handshake and checks signatures. Build a webhook receiver shows how. - A signing secret you generate:
whsec_followed by the base64 of 24 to 64 random bytes.
echo "whsec_$(openssl rand -base64 32)"
Discover the server
Every modern request carries its protocol version in params._meta and in the
MCP-Protocol-Version header, and the method in Mcp-Method:
curl https://api.emitkit.com/mcp \
-H "Authorization: Bearer $EMITKIT_AGENT_KEY" \
-H "Content-Type: application/json" \
-H "MCP-Protocol-Version: 2026-07-28" \
-H "Mcp-Method: server/discover" \
-d '{
"jsonrpc": "2.0", "id": 1, "method": "server/discover",
"params": { "_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": {}
} }
}'
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"supportedVersions": ["2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"],
"capabilities": { "tools": {}, "events": {} },
"_meta": { "io.modelcontextprotocol/serverInfo": { "name": "emitkit", "title": "EmitKit", "version": "3.0.0" } },
"instructions": "…",
"resultType": "complete"
}
}
Clients on older protocol versions start with initialize, whose capabilities
list events too. They call the same events/* methods without the headers
and _meta shown on this page. Errors from those methods arrive in an HTTP
200. A missing or invalid credential is still 401, and a spent rate limit
429.
On 2026-07-28, if a header doesn’t match the body, EmitKit answers 400 with
error -32020. An unsupported version gets 400 with -32022 and
the supported list, and an unknown method gets 404 with -32601.
The event: event.created
events/list describes it. It fires for every event a sender or agent creates
in the key’s Project (a recorded answer to a question doesn’t count), including events sent with notify: false, because notify only
controls push notifications.
All filters are optional, and every one you give must match.
| Argument | Type | Matches |
|---|---|---|
channel |
string | Events in this channel. Named the way EmitKit names channels, so "Payments" matches payments |
tags |
string[] (up to 10) | Events that carry every one of these tags |
userId |
string | Events about this user, by your user id (after alias resolution) |
| Field | Type | Notes |
|---|---|---|
id |
string | The event id, also eventId and webhook-id |
channel |
string | Channel name |
title |
string | |
description |
string or null | |
icon |
string or null | An emoji |
tags |
string[] | |
metadata |
object | As sent, including amount/currency |
userId |
string or null | |
source |
string | api, mcp or what the sender set |
createdAt |
string | ISO 8601, UTC |
url |
string | The channel in the EmitKit dashboard |
Subscribe
Call events/subscribe
{
"jsonrpc": "2.0",
"id": 2,
"method": "events/subscribe",
"params": {
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": {}
},
"name": "event.created",
"arguments": { "channel": "payments", "tags": ["failed"] },
"delivery": {
"mode": "webhook",
"url": "https://agent.example.com/hooks/emitkit",
"secret": "whsec_…"
},
"cursor": null,
"ttlMs": 86400000
}
}Send it with the headers MCP-Protocol-Version: 2026-07-28 and
Mcp-Method: events/subscribe.
Answer the verification request
Before the subscription exists, EmitKit sends a signed
{"type": "verification", "challenge": "…"} to your URL. Reply 2xx with
exactly {"challenge": "<the same value>"}. EmitKit can skip the handshake
for a URL that key or connected app verified in the last 24 hours, but
any subscribe or refresh may send one, so answer every verification
request.
Keep the subscription id
{
"id": "sub_4f0c9d8e2b7a41d6a9c3e5f7b1d2c3a4",
"refreshBefore": "2026-10-01T12:00:00.000Z",
"cursor": null,
"truncated": false,
"resultType": "complete"
}Every delivery carries this id in X-MCP-Subscription-Id. It’s derived
from the key, URL, event name and arguments, so it stays the same when you
refresh.
Refresh, rotate and stop
- Refresh by calling
events/subscribeagain with the samename,argumentsanddelivery.urlbeforerefreshBefore. Subscribing twice never creates a second subscription. Subscriptions that aren’t refreshed stop, and are deleted within the hour. - Lifetime:
ttlMsdefaults to 24 hours. EmitKit grants at least 1 minute and at most 7 days.ttlMs: nullgets 7 days: EmitKit never grants a subscription without an expiry. - Rotate the secret by refreshing with a new
delivery.secret. For the next hour, deliveries carry two signatures, one for each secret, so your receiver can switch over at its own pace. - Stop with
events/unsubscribe. It takes the samename,argumentsanddelivery.url, and answers{}even when there was nothing to remove.
{
"jsonrpc": "2.0",
"id": 3,
"method": "events/unsubscribe",
"params": {
"_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {} },
"name": "event.created",
"arguments": { "channel": "payments", "tags": ["failed"] },
"delivery": { "mode": "webhook", "url": "https://agent.example.com/hooks/emitkit" }
}
}
EmitKit doesn’t replay missed events: cursor is always null and
truncated always false. To catch up after downtime, read the dashboard
feed.
Deliveries
One event per request, as a POST with Content-Type: application/json:
POST /hooks/emitkit HTTP/1.1
Host: agent.example.com
Content-Type: application/json
webhook-id: event_k2m9x7q4r8t1v5w3y6z0a2b4
webhook-timestamp: 1790856300
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
X-MCP-Subscription-Id: sub_4f0c9d8e2b7a41d6a9c3e5f7b1d2c3a4
{
"eventId": "event_k2m9x7q4r8t1v5w3y6z0a2b4",
"name": "event.created",
"timestamp": "2026-09-30T12:05:00.000Z",
"data": {
"id": "event_k2m9x7q4r8t1v5w3y6z0a2b4",
"channel": "payments",
"title": "Payment failed",
"description": "Card declined · Pro plan",
"icon": "💳",
"tags": ["failed"],
"metadata": { "amount": 49, "currency": "EUR" },
"userId": "cus_123",
"source": "api",
"createdAt": "2026-09-30T12:05:00.000Z",
"url": "https://app.emitkit.com/acme?channelId=channel_…"
},
"cursor": null
}
| Your reply | What EmitKit does |
|---|---|
2xx |
Delivered |
408, 425, 429, 5xx, timeout (10 s) or no connection |
Tries again after 10, 20 and 40 seconds, then gives up |
410 Gone |
Deletes the subscription, and doesn’t try again. Your next refresh creates it again |
Any other 3xx or 4xx |
Doesn’t try again. Redirects are never followed |
Delivery is best effort. An event can arrive more than once, and it can be missed, because retries stop after the third and nothing replays a missed event. A retry keeps the same webhook-id (the event
id) with a fresh timestamp and signature, so use webhook-id to skip
duplicates. Events can arrive out of order.
No feedback loops
An agent that reacts to an event by creating another one would otherwise hear about its own event, react again, and so on. EmitKit never delivers an event to subscriptions of the API key or OAuth connection that created it. Give the agent its own key or connection, and use a different key for your app.
Access and limits
- The API key or OAuth connection is the subscriber. Revoke or rotate the key, revoke the connection, delete its Project, or stop being an owner or admin of the organization, and deliveries stop straight away.
- A key or connection can hold 25 subscriptions. The 26th gets
-32025withdata.limit: "subscriptions". - Subscribing needs a key that can read events: full keys and read-only keys both can.
- Every request counts toward the same 100 requests per minute as tool calls.
- Callback URLs must use
httpsand a public host name or address. EmitKit refuses credentials in the URL, private and loopback addresses (including IPv6 addresses that carry an IPv4 one, such as 6to4 and Teredo), and names such aslocalhostor*.internal, with or without a trailing dot. It never follows redirects.
Errors
| Code | Meaning | When |
|---|---|---|
-32602 |
Invalid params | Arguments outside the event’s inputSchema, a bad URL, or a secret that isn’t whsec_ plus 24 to 64 bytes |
-32023 |
Not found | Unknown event name (data.kind: "event") |
-32024 |
Forbidden | A key that isn’t bound to a Project. A missing or invalid key or token gets HTTP 401 before any method runs, and a spent rate limit HTTP 429 |
-32025 |
Resource exhausted | 25 subscriptions reached |
-32026 |
Unsupported | A delivery mode other than webhook |
-32015 |
Callback endpoint error | Verification failed. data.reason is challenge_failed, http_4xx, http_5xx, timeout, tls_error or connection_refused |