Add support for transmitting call tool responses to webhooks. Routing the responses to the webhook will be the responsibility of the transport layer, however, this specification change will standardize how webhooks can be passed from the client to the server and how the server can expose support for webhooks as a capability.

Changes:

• Introduce a new server capability to support webhooks
• Allow MCP clients to pass webhooks as part of tools/call request in CallToolRequestParams
• Introduce interfaces for Webhook and AuthenticationInfo

Motivation and Context

Discussed in #523

As MCP expands to support asynchronous communication (#491), there will arise scenarios wherein the async execution will take anywhere from a few hours to a few days. The current discussion revolves around modeling long-running executions as resources/streams that require client polling to allow the client to disconnect from the server.

In order to free up the client and reduce load when handling multiple async operations, the recommended approach is often to offer support for webhooks (similar discussion: #266). Webhooks offer a lightweight approach that allow the server to send results to the client when the async execution for a tool has been completed. Webhooks can be hosted by standalone servers (common in cloud services) or in some cases, they can be hosted by the client.

• Webhook can act as a mechanism that notifies the client once the async execution has completed before proceeding to retrieve it.
• The pattern of async execution + webhooks can also prove useful in scenarios where storing the response might make sense prior to the client interacting with it.
• Passing webhooks to different servers, that support webhooks, would allow the client to disconnect after the acknowledged response and just track responses sent to the webhook instead of querying different servers for the async responses.

Even though the webhook routing implementation will exist in the transport layer, the server will have the ability to decide whether to offer support for routing responses to webhooks or not. This decision could be based on whether the server comprises of asynchronous tools, whether the server wants to establish connections to the webhooks uris provided by the client (security concerns), if the server wants to risk additional latency of transmitting results to webhook (reliability) etc-.

If a server supports webhook capability, webhooks will be supported for all tools in the server. The client will have the option to pass webhooks as part of the CallToolsRequest. Any request with webhooks will have the final results transmitted to webhooks instead of back to the client. The client will receive an acknowledgement response once the tool call with webhooks has been received by the server.

The tool call implementations should be able to vary their behaviour depending on whether the tool call from the client consists of a webhook or not. This can be achieved by adding information to the request context about whether a webhook was passed in the request or not.

Examples

• User interacts with a client and tasks it with performing time series forecasting on stock market prices for select securities. The client interacts with a server to perform time series forecasting using ML algorithms. The time series forecasting tool on the server is modeled as asynchronous. The final response is a large dataset since the forecasting granularity is in minutes and over the period of a few months. In such a scenario, the client would provide the server with a webhook to another data store. The webhook stores the response before the client further interacts with the results.
• The user makes use of a client that is linked with their cloud service (Amazon Q, Microsoft Copilot etc-). The webhook is hosted in the user's personal account. Even when the user shuts down their local machines, the account along with the webhook will always be up and running. The user opens their local machine and uses the local client. The local client connects to a server and uses it to trigger a long running task. The user then proceeds to shut down their local client/machine. The long running task will complete on the server and the results will be transmitted to the webhook. The user logs back in after some time. As soon as the local client reconnects to the upstream service (ideally on start up), it will have the response waiting for it.

How Has This Been Tested?

• Created client and server with a draft implementation in python-sdk to test out the changes. Hosted a test webhook locally to receive the responses.
• Unit tests were successful

Breaking Changes

None

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed