---
title: "Subscribe (MCP Events)"
method: POST
path: "/tenants/{tenant_id}/mcp/events/subscribe"
tags: ["Destinations"]
---

# Subscribe (MCP Events)

`POST /tenants/{tenant_id}/mcp/events/subscribe`

## Request

- Base URL: `https://api.outpost.hookdeck.com/2025-07-01`
- URL: `https://api.outpost.hookdeck.com/2025-07-01/tenants/{tenant_id}/mcp/events/subscribe`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

**Experimental.** Serves the MCP Events `events/subscribe` method for an MCP server that
forwards the request `params` as the body. Creates a subscription, or refreshes it when
the tenant already holds the same subscription: the same tenant, event, arguments and
callback URL always give the same `id`. A new subscription is
verified with a challenge to its callback URL before it is stored; one that has expired is
replaced by a new one. The tenant is created if it does not exist, even when the subscribe then fails. Admin API key only;
answers `404` while MCP is not enabled (`EXPERIMENTAL_MCP_ENABLED`).

Failures answer `422` with an `mcp_error` the MCP server returns as its JSON-RPC error.

## Request body

- object: The `events/subscribe` params, forwarded as received.

## Response `200`

The `events/subscribe` result.

- object
  - `resultType` 'complete', required
  - `id` string, required
  - `refreshBefore` string, date-time, nullable, required: Subscribe again before this time to keep the subscription. Null only when the request sent `ttlMs: null`, which means the subscription does not expire.
  - `cursor` string, nullable, required: Always null; events are not replayed.
  - `truncated` boolean, required: Always false; events are not replayed.
  - `deliveryStatus` object: Present when an existing subscription was refreshed.
    - `active` boolean, required: False when the subscription was suspended before this refresh. The refresh re-enables it.

## Other responses

- `401`: Missing or invalid authentication credentials.
- `403`: The credentials are valid but not allowed to perform the request.
- `404`: Requested resource not found.
- `413`: Request body is larger than 1 MiB.
- `422`: The MCP request failed. `mcp_error` is a JSON-RPC error object with `data` only where the MCP Events spec defines it: `-32602` invalid params (a malformed request body also answers this) has no `data`, `-32023` not found (`data.kind` is `event` or `subscription`), `-32025` resource exhausted (`data.limit`, and `data.max` when there is one), `-32026` unsupported (`data.feature` and `data.value`, such as a delivery mode other than `webhook`), `-32027` callback endpoint error (`data.reason` names the failure category).
- `500`: Unexpected server error.
- `503`: A subscription's callback verification could not run (`data.code` is `verification_unavailable`), the subscription is being changed by concurrent requests (retry), or the MCP event definitions are invalid (the reason is in the server log).

## Changes

- **2026-11-12** `74708d21de8c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/hookdeck/apis/outpost-api/changes/tenants/:tenant_id/mcp/events/subscribe/post.md)

---

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