MCP Events is a draft extension to the Model Context Protocol (MCP) that lets an agent subscribe to events an MCP server exposes, such as a new order in a store or a failed build in CI, and react without a user in the loop. In webhook mode, the agent gives your MCP server a callback URL and a signing secret, and each matching event is sent to that URL as a webhook signed with Standard Webhooks. For the background, read What are MCP Events?.

Delivering those webhooks reliably means signing each one, retrying failed deliveries and storing subscriptions until they expire. Since v1.9.0, Hookdeck Outpost does that work through its MCP Events support, and checks each callback URL as well. Your MCP server authenticates the agent, forwards three MCP methods to Outpost, and publishes events.

This guide adds an order.created event to a TypeScript MCP server and tests it with the demo's test subscriber, subscribed to high-value orders. The snippets are fragments adapted from the MCP Events with Hookdeck Outpost demo, which has the complete, runnable code.

MCP Events is a draft

MCP Events is proposed in SEP-3415: Events Extension, a Specification Enhancement Proposal (SEP) from the MCP Triggers and Events Working Group. The SEP isn't part of the MCP specification yet, so details may change. Outpost's support is experimental for the same reason, and off by default.

Outpost implements SEP-3415 as of November 2026. ChatGPT implements MCP Events as OpenAI's MCP Events implementer guide describes it, which differs from the SEP on the webhook-id header and on error codes. Compatibility with other MCP Events implementations explains what that means for your server.

How a subscription flows through Outpost

1. events/subscribe to order.created, USD, high value2. Forward to the principal's tenant3. Signed verification challengeChallenge echoedSubscriptionSubscription4. Publish order.created5. Signed MCP event (filtered, retried)An order is placedAgent (subscriber)Your MCP serverHookdeck OutpostAgent (subscriber)Your MCP serverHookdeck Outpost
1.events/subscribetoorder.created,USD, highvalue2. Forward tothe principal'stenant3. Signed verificationchallengeChallenge echoedSubscriptionSubscription4. Publishorder.created5. Signed MCP event(filtered, retried)An order isplacedAgent(subscriber)Your MCPserverHookdeckOutpostAgent(subscriber)Your MCPserverHookdeckOutpost
  1. The agent calls events/subscribe on your MCP server. The request names the event, optional arguments that filter it, a callback URL, and a signing secret the agent generated (a whsec_ value, the Standard Webhooks format).
  2. Your server authenticates the agent to find its principal, the user or account the subscription belongs to. It maps the principal to an Outpost tenant, which holds that principal's subscriptions, and forwards the request to Outpost.
  3. Outpost sends a signed challenge to the callback URL, and the agent echoes it back. Outpost then stores the subscription and returns it, and your server returns it to the agent.
  4. When an order is placed, your server publishes the event to Outpost.
  5. Outpost delivers the event to every subscription whose arguments match. It wraps the event data in the MCP event envelope (eventId, name, timestamp, data and cursor), signs it and retries failed deliveries.

Before the subscription expires, the agent refreshes it by calling events/subscribe again, and it calls events/unsubscribe when it's done. Your server forwards both calls to Outpost. Outpost sends each delivery directly to the callback URL, so deliveries never pass through your server.

Prerequisites

  • An MCP server in TypeScript. Use v2 of the official MCP TypeScript SDK (@modelcontextprotocol/server and @modelcontextprotocol/node), which implements the 2026-07-28 version of the MCP specification, one of the versions ChatGPT supports for MCP Events.
  • Outpost with MCP Events support. A Hookdeck account with a managed Outpost project and an API key from the project's Settings > Secrets, or a self-hosted Outpost at v1.9.0 or later and its API key.
  • Authentication. Each webhook subscription belongs to its principal, the authenticated caller who created it. With OAuth, the principal is the sub claim of a verified access token. SEP-3415 says a server that can't identify callers must not offer webhook mode. For a short-lived dev test, you can map every request to one fixed principal.
  • Public https URLs to test with. Outpost only delivers to https URLs on public addresses, so the agent's callback URL needs one. This guide uses the Hookdeck CLI, installed and logged in. To test with ChatGPT, your MCP server needs a public https URL too, and you need a ChatGPT plan with Developer mode.

Set up the project

The examples use Node.js with TypeScript, Express for the HTTP server, and the Outpost TypeScript SDK for publishing. The SDK has no methods for the MCP Events routes yet, so the examples call those with fetch. Install the packages in an ES module project ("type": "module" in package.json):

Shell
npm install @modelcontextprotocol/server @modelcontextprotocol/node @hookdeck/outpost-sdk zod express standardwebhooks
npm install --save-dev typescript tsx @types/node @types/express

Set your Outpost API URL and key. For managed Outpost, the URL is https://api.outpost.hookdeck.com/2025-07-01. For self-hosted Outpost, use your instance's API URL, such as http://localhost:3333/api/v1.

Shell
export OUTPOST_API_URL=https://api.outpost.hookdeck.com/2025-07-01
export OUTPOST_API_KEY=<your Outpost API key>

The snippets in the steps below share these imports and definitions:

server.ts
ts
import { createHash } from "node:crypto";
import express from "express";
import * as z from "zod";
import {
  McpServer,
  ProtocolError,
  createMcpHandler,
  type ServerCapabilities,
} from "@modelcontextprotocol/server";
import { toNodeHandler } from "@modelcontextprotocol/node";
import { Outpost } from "@hookdeck/outpost-sdk";

const OUTPOST_API_URL = process.env.OUTPOST_API_URL!;
const outpost = new Outpost({
  apiKey: process.env.OUTPOST_API_KEY!,
  serverURL: OUTPOST_API_URL,
});

// Params of the three MCP methods, sent to Outpost unchanged.
const anyParams = z.record(z.string(), z.unknown());
type Params = Record<string, any>;

const sha256 = (value: string) =>
  createHash("sha256").update(value).digest("hex");

// Subscription lifetime limits (Step 3).
const DEFAULT_TTL_MS = 60 * 60 * 1000;
const MIN_TTL_MS = 60 * 1000;
const MAX_TTL_MS = 24 * 60 * 60 * 1000;

// Tenants that have subscribed. Step 4 publishes to each one.
// In production, store this set in your database.
const subscribedTenants = new Set<string>();

Run the server with npx tsx server.ts.

Step 1: Turn on MCP Events and 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:

mcp-events.json
json
{
  "events": [
    {
      "name": "order.created",
      "description": "Fires when a new order is placed. Optionally filter by currency, or to high-value orders (a total of 100 or more).",
      "delivery": ["webhook"],
      "inputSchema": {
        "type": "object",
        "properties": {
          "currency": { "type": "string", "enum": ["USD", "EUR", "GBP"] },
          "highValue": { "type": "boolean" }
        }
      },
      "payloadSchema": {
        "type": "object",
        "properties": {
          "orderId": { "type": "string" },
          "total": { "type": "number" },
          "currency": { "type": "string" },
          "highValue": { "type": "boolean" },
          "itemCount": { "type": "integer" },
          "customerName": { "type": "string" },
          "createdAt": { "type": "string", "format": "date-time" }
        },
        "required": ["orderId", "total", "currency", "highValue", "itemCount", "customerName", "createdAt"]
      }
    }
  ]
}
  • name is the event name. It's also the Outpost topic you publish to, so add order.created to the project's TOPICS setting.
  • payloadSchema is required. It describes the event data you publish in Step 4.
  • inputSchema lists the subscription arguments. Each argument names a top-level field of the event data, and Outpost delivers an event to a subscription only if every argument equals the matching field. Without an inputSchema, every top-level string, number, integer or boolean field is an optional argument.

Arguments can only test equality, so "orders of 100 or more" can't be an argument. The example adds a boolean highValue field that your server sets on each order, and agents filter on that.

Turn MCP Events on and set the definitions:

Set EXPERIMENTAL_MCP_ENABLED and EXPERIMENTAL_MCP_EVENTS_SCHEMA through Outpost's Config API (PATCH /config), with the definitions as inline JSON. A new TOPICS value replaces the project's list, so the command reads the current topics first and adds order.created to them:

Shell
TOPICS=$(curl -s "$OUTPOST_API_URL/config" \
  -H "Authorization: Bearer $OUTPOST_API_KEY" | jq -r '.TOPICS // ""')

curl -s -o /dev/null -w '%{http_code}\n' -X PATCH "$OUTPOST_API_URL/config" \
  -H "Authorization: Bearer $OUTPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg events "$(jq -c . mcp-events.json)" --arg topics "$TOPICS" '{
    EXPERIMENTAL_MCP_ENABLED: "true",
    EXPERIMENTAL_MCP_EVENTS_SCHEMA: $events,
    TOPICS: ($topics | split(",") | map(select(. != "")) + ["order.created"] | unique | join(","))
  }')"

The PATCH request restarts the deployment, so wait about a minute before you run the check below the tabs.

You can also turn MCP Events on, import the definitions and edit them in the Hookdeck dashboard's MCP Events settings. Each of the project's topics is a row there, and a topic becomes an MCP event once it has a payload schema.

Set these environment variables, and restart Outpost:

Shell
EXPERIMENTAL_MCP_ENABLED=true
EXPERIMENTAL_MCP_EVENTS_SCHEMA=/path/to/mcp-events.json
TOPICS=order.created

EXPERIMENTAL_MCP_EVENTS_SCHEMA takes inline JSON or the path of a JSON or YAML file. See MCP Events configuration for the other options, including insecure callbacks for local development.

List the events to check that Outpost applied your configuration. Outpost responds 404 while MCP Events is off, and 503 while the event definitions are invalid. In the invalid case, Outpost's logs name the event and the field that failed validation.

Shell
curl -s "$OUTPOST_API_URL/mcp/events/list" \
  -H "Authorization: Bearer $OUTPOST_API_KEY" | jq '.events[].name'

Step 2: Declare the events capability and handle events/list

An MCP client calls server/discover to learn what your server supports, so advertise MCP Events in its response. OpenAI's guide shows an empty events object, and SEP-3415 declares the extension under extensions, so declare both events and extensions.

The MCP TypeScript SDK has no MCP Events support yet. Cast the capabilities to ServerCapabilities, and register events/list, events/subscribe and events/unsubscribe as custom request handlers on the low-level Server that McpServer wraps:

ts
function buildMcpServer(principal: string | undefined) {
  const mcpServer = new McpServer(
    { name: "my-store", version: "1.0.0" },
    {
      capabilities: {
        events: {},
        extensions: { "io.modelcontextprotocol/events": {} },
      } as ServerCapabilities,
    },
  );
  const { server } = mcpServer;
  server.setRequestHandler(
    "events/list",
    { params: anyParams.optional() },
    (params) => {
      // Forward the client's cursor so it can page through the list.
      const cursor = typeof params?.cursor === "string" ? params.cursor : undefined;
      const query = cursor ? `?cursor=${encodeURIComponent(cursor)}` : "";
      return callOutpost("GET", `/mcp/events/list${query}`);
    },
  );
  server.setRequestHandler(
    "events/subscribe",
    { params: anyParams },
    (params) => subscribe(principal, params),
  );
  server.setRequestHandler(
    "events/unsubscribe",
    { params: anyParams },
    (params) => unsubscribe(principal, params),
  );
  return mcpServer;
}

const mcp = toNodeHandler(
  createMcpHandler((ctx) => buildMcpServer(ctx.authInfo?.clientId)),
);

const app = express();

app.post("/mcp", async (req, res) => {
  // You write authenticate(). It verifies the access token and returns the principal.
  const { token, principal } = await authenticate(req);
  if (!principal) return res.status(401).end();
  Object.assign(req, { auth: { token, clientId: principal, scopes: [] } });
  await mcp(req, res);
});

app.listen(3000);

createMcpHandler creates a new MCP server for each incoming request, which is why buildMcpServer takes the principal as an argument. The example passes the principal in through the clientId field of req.auth.

Authenticate each /mcp request before you pass it to mcp. Verify the OAuth access token, use its sub claim as the principal, and respond 401 if the token is missing or invalid. For a dev test with ChatGPT's No Authentication option, use one fixed principal such as "dev".

events/list returns the definitions from Step 1, 50 per page by default. The handler forwards the client's cursor, so a client can follow the nextCursor in each page to the next one. The Outpost route also accepts a topics query parameter (for example ?topics=order.created), which you can use to list only the events a principal may see.

Step 3: Forward events/subscribe and events/unsubscribe

Outpost serves the MCP Events methods on three routes, which you call with your Outpost API key:

MCP methodOutpost route
events/listGET /mcp/events/list
events/subscribePOST /tenants/{tenant_id}/mcp/events/subscribe
events/unsubscribePOST /tenants/{tenant_id}/mcp/events/unsubscribe

When Outpost accepts a request, it responds 200 with the MCP result, and your server returns that body as the method's result. When Outpost refuses a request, it responds 422 with an mcp_error, which is already a JSON-RPC error object, and your server returns it as the method's error. callOutpost maps both cases:

ts
async function callOutpost(method: "GET" | "POST", path: string, body?: unknown) {
  const response = await fetch(`${OUTPOST_API_URL}${path}`, {
    method,
    headers: {
      Authorization: `Bearer ${process.env.OUTPOST_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: body === undefined ? undefined : JSON.stringify(body),
    // Subscribe waits for Outpost to verify the callback URL.
    signal: AbortSignal.timeout(40_000),
  });
  const json = await response.json().catch(() => ({}));
  if (response.ok) return json;
  if (json.mcp_error) {
    const { code, message, data } = json.mcp_error;
    throw new ProtocolError(code, message, data);
  }
  // Outpost returned 404 (MCP Events is off) or 503 (invalid event definitions,
  // or verification briefly unavailable). Log the response, and don't expose it
  // to the client.
  throw new ProtocolError(-32603, "MCP Events is unavailable");
}

Before your server forwards a subscribe request, it maps the principal to a tenant, checks the principal may receive the event, and sets the subscription's lifetime.

Map each principal to a tenant

In Outpost, a tenant groups the subscriptions that belong to one principal (see multi-tenancy). Your server derives the tenant from the authenticated principal, never from anything in the request, so an agent can't subscribe on behalf of someone else. Outpost creates the tenant the first time that principal subscribes.

ts
function tenantIdFor(principal: string) {
  return /^[A-Za-z0-9_-]{1,48}$/.test(principal)
    ? `mcp_${principal}`
    : `mcp_${sha256(principal).slice(0, 24)}`;
}

Use one tenant per principal. SEP-3415 identifies a subscription by principal, callback URL, event name and arguments, and Outpost uses the tenant in place of the principal. If two principals shared a tenant and subscribed to the same event with the same arguments and callback URL, they would share one subscription, and either could change or remove it.

Check access to the event

Check that the principal is allowed to receive the requested event with the requested arguments. For example, a user might be allowed to see orders for one store but not another. SEP-3415 requires this check, and Outpost doesn't know your access rules, so you write assertMayReceive. Have it throw a ProtocolError with code -32024 (SEP-3415's Forbidden) to refuse the subscription.

Set the lifetime

ttlMs is the subscription's lifetime in milliseconds. The agent may suggest a value, and Outpost grants exactly the value your server sends. If the request has no ttlMs, Outpost uses 24 hours. null means no expiry, and 0 or less expires the subscription immediately. Apply your own limits before you forward the request.

ts
function grantTtlMs(requested: unknown) {
  if (requested === undefined) return DEFAULT_TTL_MS; // for example one hour
  if (requested === null) return MAX_TTL_MS; // don't grant "never"
  if (typeof requested !== "number")
    throw new ProtocolError(-32602, "ttlMs must be a number");
  return Math.min(Math.max(requested, MIN_TTL_MS), MAX_TTL_MS);
}

Forward the subscribe request

With those three helpers, the subscribe handler forwards the request's params, with the lifetime your server granted:

ts
async function subscribe(principal: string | undefined, params: Params) {
  // SEP-3415 answers a call without an authenticated principal with Forbidden.
  if (!principal)
    throw new ProtocolError(-32024, "An authenticated principal is required");
  const tenantId = tenantIdFor(principal);
  await assertMayReceive(principal, params.name, params.arguments);
  const result = await callOutpost(
    "POST",
    `/tenants/${encodeURIComponent(tenantId)}/mcp/events/subscribe`,
    { ...params, ttlMs: grantTtlMs(params.ttlMs) },
  );
  subscribedTenants.add(tenantId); // for publishing in Step 4
  return result;
}
events/subscribe request from an agent
json
{
  "name": "order.created",
  "arguments": { "currency": "USD", "highValue": true },
  "delivery": {
    "mode": "webhook",
    "url": "https://receiver.example.com/mcp-events/abc123",
    "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
  },
  "ttlMs": 3600000
}

Outpost's response is the events/subscribe result, and your server returns it to the agent. refreshBefore is the time by which the agent must call events/subscribe again to keep the subscription. cursor is always null, because Outpost doesn't replay past events.

Outpost response (the events/subscribe result)
json
{
  "resultType": "complete",
  "id": "sub_19ae44be6a97f6ba5ea1c7d281573781",
  "refreshBefore": "2026-11-13T19:06:53Z",
  "cursor": null,
  "truncated": false
}

When Outpost receives the request, it:

  1. Validates it. A malformed request, an argument that isn't in inputSchema, or a secret that isn't whsec_ followed by the base64 of 24 to 64 bytes gets error -32602 (InvalidParams). An unknown event gets -32023 (NotFound).
  2. Checks the callback URL, which must be https on a public address. Outpost doesn't follow redirects.
  3. Sends a signed {"type": "verification", "challenge": "..."} to the callback URL, which must respond 2xx and echo the challenge. If it doesn't, the subscribe fails with -32027 (CallbackEndpointError) and a data.reason such as connection_refused or challenge_failed. Outpost remembers a passed check for each tenant and callback URL, so refreshes don't repeat it.
  4. Stores the subscription, or refreshes it if it already exists. A repeated subscribe with the same event, arguments and callback URL gets the same id and a new expiry. If a refresh brings a new secret, Outpost signs with both secrets for 24 hours, so the receiver can switch over.

Unsubscribe

For events/unsubscribe, your server forwards params to the unsubscribe route for the principal's tenant. The name, arguments and delivery.url in params identify the subscription to remove.

If no such subscription exists, Outpost responds with NotFound. OpenAI's guide says unsubscribe must succeed in that case, so catch that error and return success:

ts
async function unsubscribe(principal: string | undefined, params: Params) {
  if (!principal)
    throw new ProtocolError(-32024, "An authenticated principal is required");
  const path = `/tenants/${encodeURIComponent(tenantIdFor(principal))}/mcp/events/unsubscribe`;
  try {
    return await callOutpost("POST", path, params);
  } catch (error) {
    const gone =
      error instanceof ProtocolError &&
      error.code === -32023 &&
      (error.data as { kind?: string } | undefined)?.kind === "subscription";
    if (!gone) throw error;
    return { resultType: "complete" };
  }
}

Try a subscription

The demo has a test subscriber you can point at your server. Outpost only delivers to a public https URL, so the test subscriber's callback URL is a Hookdeck MCP Events source: the source answers Outpost's verification challenge, and the Hookdeck CLI forwards each delivery to the test subscriber on your machine. Test MCP Events deliveries locally with the Hookdeck CLI explains this setup and what else you can check with it.

With your server running, clone and install the demo. Then create a signing secret and an MCP Events source that holds it, and note the source's url:

Shell
git clone https://github.com/hookdeck/mcp-events-outpost-demo
cd mcp-events-outpost-demo
npm install

export SECRET="whsec_$(openssl rand -base64 32)"
hookdeck gateway source create --name mcp-events-test --type MCP_EVENTS \
  --webhook-secret "$SECRET" --output json
export SOURCE_URL=<the url from the output>

In a second terminal, forward the source's deliveries to port 4000, where the test subscriber listens, and leave it running:

Shell
hookdeck listen 4000 mcp-events-test

Back in the first terminal, run the test subscriber with your server's /mcp URL, a bearer token that your authenticate() accepts, and the source's URL and secret:

Shell
MCP_SERVER_URL=http://localhost:3000/mcp MCP_TOKEN=<token> npm run client -- \
  --currency USD --high-value --callback-url "$SOURCE_URL" --secret "$SECRET"

The test subscriber prints the subscription id. Leave it running for Step 4. When you stop it with Ctrl+C, it unsubscribes.

To test without a Hookdeck account, the demo's npm run tunnel starts a cloudflared quick tunnel instead, and the test subscriber then answers the challenge itself. The demo's README has the steps.

Step 4: Publish events

Publish the event data that your payloadSchema describes. For each matching subscription, Outpost wraps the data in the MCP event envelope and uses the id you pass to outpost.publish() as the envelope's eventId.

outpost.publish() takes one tenant, so your server needs to know which tenants have subscribed. The subscribe handler in Step 3 records them in subscribedTenants. In production, store that list durably so it survives a restart.

Call publishOrder wherever your app creates orders:

ts
type OrderInput = {
  orderId: string;
  total: number;
  currency: string;
  itemCount: number;
  customerName: string;
};

async function publishOrder(input: OrderInput) {
  const order = {
    ...input,
    highValue: input.total >= 100,
    createdAt: new Date().toISOString(),
  };
  const results = [];
  for (const tenantId of subscribedTenants) {
    try {
      results.push(
        await outpost.publish({
          id: `evt_${order.orderId}_${sha256(tenantId).slice(0, 8)}`,
          tenantId,
          topic: "order.created",
          eligibleForRetry: true,
          time: new Date(order.createdAt),
          data: order,
        }),
      );
      // Each result's destinationIds lists the subscriptions whose arguments matched.
    } catch (error) {
      // One tenant's failure shouldn't stop the rest. Log it, and retry it from a queue in production.
      console.error(`Publishing to ${tenantId} failed`, error);
    }
  }
  return results;
}

Outpost delivers the event to every subscription in the tenant whose arguments match. Publishing to a tenant with no matching subscription delivers nothing.

Give each tenant's publish its own event ID, as the example does. Outpost uses the event ID as an idempotency key across the whole project, so a second publish with the same ID, even to another tenant, returns duplicate: true and isn't delivered.

To test publishing, add a temporary route that calls publishOrder:

ts
app.post("/orders", express.json(), async (req, res) => {
  // Use a new order ID for each request, because Outpost drops a repeated event ID as a duplicate.
  res.json(await publishOrder({ ...req.body, orderId: `ord_${Date.now()}` }));
});

Then publish one order that matches your test subscription and one that doesn't:

Shell
curl -s localhost:3000/orders -H "Content-Type: application/json" \
  -d '{"total":150,"currency":"USD","itemCount":1,"customerName":"Ada"}'
curl -s localhost:3000/orders -H "Content-Type: application/json" \
  -d '{"total":20,"currency":"EUR","itemCount":1,"customerName":"Grace"}'

The first returns the subscription's id in destinationIds, and the test subscriber prints the event. The second returns an empty destinationIds, and Outpost delivers nothing.

Step 5 (optional): Verify deliveries if you build the subscriber

If you're building the agent side, for example in your own agent runtime or to test your server, verify each delivery with a Standard Webhooks library before you trust it. The example uses Webhook from the standardwebhooks package. When ChatGPT is the agent, it verifies deliveries itself.

Each delivery is a POST with the MCP event envelope as its body and these headers:

HeaderValue
webhook-idA msg_ ID for this delivery (one event on one subscription), the same on every retry
webhook-timestampUnix seconds, new on every attempt
webhook-signaturev1,<signature>, one entry per valid secret
X-MCP-Subscription-IdThe subscription id

Give each subscription its own callback path, and store its secret under that path before you call events/subscribe. Outpost sends the verification challenge before events/subscribe returns, so the receiver doesn't have the subscription ID yet and must look up the secret by path:

ts
app.post(
  "/mcp-events/:path",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const raw = req.body.toString("utf8");
    const secrets = secretsForPath(req.params.path); // the current secret, plus the previous one during rotation
    const verified = secrets.some((secret) => {
      try {
        new Webhook(secret).verify(raw, {
          "webhook-id": req.header("webhook-id") ?? "",
          "webhook-timestamp": req.header("webhook-timestamp") ?? "",
          "webhook-signature": req.header("webhook-signature") ?? "",
        });
        return true;
      } catch {
        return false;
      }
    });
    if (!verified) return res.status(401).end();

    const body = JSON.parse(raw);
    if (body.type === "verification")
      return res.json({ challenge: body.challenge });
    if (alreadySeen(req.header("webhook-id"))) return res.status(200).end();
    enqueue(body); // persist first, process asynchronously
    res.status(200).end();
  },
);
  • Verify the signature against the raw request body. Re-serializing the parsed JSON can change the bytes and break the signature.
  • The library rejects deliveries whose timestamp is more than 5 minutes old, as SEP-3415 recommends.
  • A body with a top-level type, such as the verification challenge, is a control message. Any other body is an event.
  • Deduplicate on webhook-id, because retries can deliver the same event more than once. If you also deduplicate on the body's eventId, include the subscription in the key, because one event is delivered once to each matching subscription.
  • Return 2xx only after you've stored the event. Outpost treats any other response as a failed delivery and retries it on a fixed schedule (see Current limits), except a 410 or 413, which it doesn't retry.

Step 6: Test with ChatGPT

ChatGPT can subscribe to your server's events and run a task for each delivery. ChatGPT connects to your MCP server from OpenAI's cloud, so the server needs a public https URL, either a deployment or a tunnel.

  1. Turn on Developer mode, available on ChatGPT Plus or above. If Add custom MCP server appears in the Add menu on the Plugins page, it's already on.

  2. Go to Plugins, choose Add > Add custom MCP server, and paste your server's /mcp URL.

  3. Choose the authentication your server supports, select Create as a plugin, then Connect. ChatGPT calls server/discover, tools/list and events/list on your server.

  4. Start a new chat and switch it to Work at the top. MCP Events only run in Work chats. Type @, pick your plugin, and ask it to subscribe:

    Prompt to paste into ChatGPT
    Subscribe to high-value orders in USD. When one arrives, summarize the order in one sentence.
    

    In our test, ChatGPT sent an events/subscribe call, and the subscription became a task with the MCP event as its trigger.

  5. Place an order that matches and one that doesn't. Only the matching one is delivered.

  6. Open Scheduled in ChatGPT to see the task runs. The task's panel shows the latest run, and Open chat shows every run.

  7. Delete the task in Scheduled to unsubscribe. ChatGPT sends events/unsubscribe, and Outpost deletes the subscription.

In testing with the demo and Outpost v1.9.0 in November 2026, ChatGPT accepted Outpost's deliveries and ran the task. Testing in October 2026 also showed three ChatGPT behaviors that affect subscriptions:

  • ChatGPT doesn't send ttlMs, so the default your server grants decides how often ChatGPT refreshes.
  • Removing the plugin stops the refreshes but sends no events/unsubscribe, so the subscription stays active until it expires.
  • Asking ChatGPT to subscribe again creates a second subscription with a new callback URL, so one event then triggers two deliveries and two task runs.

Compatibility with other MCP Events implementations

Outpost follows SEP-3415 where it differs from OpenAI's implementer guide, on the webhook-id header and on error codes.

The webhook-id header is a random msg_ ID for each delivery, as SEP-3415 requires. OpenAI's guide says it must equal the body's eventId, but ChatGPT still accepts Outpost's deliveries.

The Vercel AI SDK's MCP Events webhook handler (experimental_createMCPEventWebhook in @ai-sdk/mcp 2.0.99) checks that the two match and responds 400 when they don't, so an agent built on it never receives Outpost's deliveries. Outpost v1.9.0 has no setting for the webhook-id value, so there's no workaround on the Outpost side yet.

Outpost's error codes are SEP-3415's, such as -32023 (NotFound), -32024 (Forbidden) and -32027 (CallbackEndpointError). OpenAI's guide gives -32015 for CallbackEndpointError instead.

Current limits

  • An argument can only test equality. It can't express a range, a list of values or a transform. Add a derived field to filter on, as highValue does, or leave the argument out.
  • Outpost retries an MCP delivery 1, 3, 5 and 5 minutes after the previous attempt, five attempts in all over 14 minutes. The project's RETRY_SCHEDULE and MAX_RETRY_LIMIT settings don't apply, and you can't retry a failed MCP delivery manually.
  • Outpost supports webhook delivery only. SEP-3415 also defines poll and push delivery. ChatGPT uses webhook delivery.

Before you go to production

The demo maps bearer tokens to principals and lets every principal receive every order. For production, replace the token mapping with OAuth, write an assertMayReceive that enforces your access rules, and keep the set of subscribed tenants in a database.

Complete example

The MCP Events with Hookdeck Outpost demo is a working MCP server built this way. It was tested against Outpost v1.9.0, with ChatGPT and with Outpost's mcp-dev check, which runs SEP-3415's webhook rules against an MCP Events server. The demo passed every rule except two where it follows OpenAI's guide for ChatGPT, and its README lists both. It includes a test subscriber that answers challenges and verifies deliveries, and a mock Outpost for offline tests.

These files map to the steps above: