MCP Events

RouterMCP can expose webhook events from eligible upstream MCP servers through the same authenticated project endpoint used for MCP tools. This feature is available only when event support is enabled for the gateway and your project.

Eligibility

• An upstream must implement MCP Events with webhook delivery. RouterMCP does not turn a tools-only server into an event source, and hosted connectors do not gain event methods automatically.
• Event definitions are discovered with the credentials and permissions of the current caller. Events from another user or project are not included.
• The first release supports webhook delivery. Polling and streaming sources are not converted into webhooks.
• ChatGPT supports this flow in Work chats on supported web and desktop clients when Cloud is selected. Availability depends on the ChatGPT workspace and client.

Configure every upstream with its actual MCP 2.0 POST endpoint; RouterMCP sends Events requests to that exact URL, does not append /mcp, and does not follow redirects.

Event names include the RouterMCP server alias, for example github__issue.opened, so two upstream servers can expose the same original event name without colliding.

Discovery and subscriptions

The MCP client discovers event support with server/discover, then lists permitted definitions with events/list. A definition includes its event name, description, input schema, payload schema, and webhook delivery mode. The client can paginate the catalog with the returned cursor.

Subscribing verifies the callback endpoint before accepting event data. Callback endpoints must use HTTPS, accept a signed challenge, and avoid redirects. RouterMCP checks the callback signature and stores subscription state so delivery can continue after a process restart. Each project can hold up to 1,000 concurrent subscription slots, with a limit of 100 per user or API key; event ingress is limited to 1,000 accepted events per project per UTC minute. The callback secret is kept separate from the upstream server's secret.

The subscription lifetime is always finite, even when the upstream source cannot provide an expiry. RouterMCP rejects an upstream grant that does not report a finite refresh time.

Each occurrence is delivered as one signed webhook request with a 262,144-byte body limit. RouterMCP retries eligible temporary failures with a bounded retry policy and records callback receipt status. A successful HTTP response means the callback received the request; it does not prove that ChatGPT completed a task or produced a reaction. An expired or oversized occurrence stops retrying without automatically stopping the whole subscription.

Lifetime and history

Subscriptions have a finite lifetime. RouterMCP grants no more than 24 hours at a time, and an upstream server may grant a shorter period. A subscription that needs to continue must be refreshed before it expires.

The initial release does not support event replay. Subscribe responses and delivered occurrences use a null cursor. Requesting a non-null replay cursor is unsupported; an upstream event source may also report that its history was truncated.

Monitor and stop subscriptions

After event support is enabled for your project, rescan or reconnect the MCP server in ChatGPT so it discovers the current event catalog. Open your project and choose Events to see the subscriptions available to your account, their expiry, and delivery status. Project owners and admins can review and stop project subscriptions. Stopping cancels queued deliveries and prevents later retries while RouterMCP retries cleanup at the upstream server. An HTTP request that was already in flight may still arrive.

The page shows event and delivery metadata only. It does not expose callback URLs, signing secrets, request headers, or event payloads.

Troubleshooting

• If no events appear, confirm the upstream implements webhook events, the current account has access to the source, and event support is enabled for the project.
• If callback verification fails, check that the client can receive HTTPS requests and return the signed verification challenge. Redirecting callback URLs are not accepted.
• If a subscription expires, ask the client to subscribe again. Existing event history is not replayed.
• If deliveries fail, use the project Events page to review the categorized status and retry count. Contact the project owner if the source server or its credentials need attention.