Skip to content
EmitKitDocs
Esc
↑↓navigate↵open⌘Jpreview
On this page

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 https URL 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/subscribe again with the same name, arguments and delivery.url before refreshBefore. Subscribing twice never creates a second subscription. Subscriptions that aren’t refreshed stop, and are deleted within the hour.
  • Lifetime: ttlMs defaults to 24 hours. EmitKit grants at least 1 minute and at most 7 days. ttlMs: null gets 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 same name, arguments and delivery.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 -32025 with data.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 https and 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 as localhost or *.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

Was this page helpful?