---
title: "Subscribe to MCP Events"
method: POST
path: "/api/v1/app/{app_id}/mcp-events/subscribe"
tags: ["Endpoint"]
---

# Subscribe to MCP Events

`POST /api/v1/app/{app_id}/mcp-events/subscribe`

## Request

- Base URL: `https://api.eu.svix.com`
- URL: `https://api.eu.svix.com/api/v1/app/{app_id}/mcp-events/subscribe`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/svix/apis/svix-api/docs/api/v1/app/:app_id/mcp-events/subscribe/post.ts> (a function with typed inputs; its response is checked against the schema)

Create or refresh an MCP Events subscription.

## Path parameters

- `app_id` string, required: The Application's ID or UID.

## Headers

- `idempotency-key` string

## Request body

- McpEventsSubscribeIn
  - `arguments` object: The filter arguments of the `events/subscribe` request, as described by the event's `inputSchema` (e.g. `{"document_id": "doc_123"}`). Together with `name` and the callback URL they identify the subscription They're stored in the endpoint's `mcpEventArguments` metadata, but aren't used to filter messages; use `channels` for that. See [Create a subscription](https://developers.openai.com/plugins/build/mcp-events#create-a-subscription) in OpenAI's MCP Events docs.
  - `challengeMode` 'challenge-response' | 'echo': How an endpoint must respond to a challenge. - `challenge-response`: the Standard Webhooks challenge-response check. The endpoint must return `webhook-challenge-response`, calculated from the challenge and its secret. - `echo`: the endpoint must echo the challenge from the request body back as `{"challenge": "..."}`. This doesn't prove that it holds the secret.
  - `channels` string[], nullable: Only send messages with one of these channels to the subscription, for example ones derived from `arguments`. Omit to send all messages of the event type.
  - `delivery` McpEventsSubscribeDeliveryIn, required
    - `mode` 'webhook', required
    - `secret` string, required: The secret events are signed with. MCP Events requires a `whsec_` secret.
    - `url` string, uri, required: The callback URL events are sent to.
  - `name` string, required: The event to subscribe to. It must be an existing event type.
  - `secretGracePeriodSeconds` integer, nullable: How long the previous secret keeps signing when a refresh changes it, in seconds. Valid values are between 0 (immediate expiry) and 7 days. The default is 5 minutes.
  - `ttlMs` integer, nullable: The requested lifetime of the subscription, in milliseconds. Omit for the default of 7 days, or set to `null` for a subscription that never expires.

## Response `200`

- McpEventsSubscribeOut
  - `cursor` string, nullable: Always `null`, since events can't be replayed.
  - `endpointId` string, required: The Endpoint's ID.
  - `id` string, required: The subscription's ID, which is also the UID of its endpoint.
  - `refreshBefore` string, date-time, nullable: When the subscription expires, or `null` if it never does.
  - `truncated` boolean, required: Always `false`, since events can't be replayed.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `422`: Validation Error
- `429`: Too Many Requests

## Changes

- **2026-11-04** `7ac277daf2b7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/svix/apis/svix-api/changes/api/v1/app/:app_id/mcp-events/subscribe/post.md)

---

[API](https://skmtc.dev/svix/apis/svix-api.md) - [All operations](https://skmtc.dev/svix/apis/svix-api/llms.txt) - [OpenAPI document](https://skmtc.dev/svix/apis/svix-api/revisions/f2cb264ac18a?raw)