René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"SEP-992: Notification Configuration for Tool Call Result","articleBody":"## Preamble\n\n**Authors:** [Mathis Joffre](mailto:mjoffre@blaxel.ai)\n\n## Abstract\n\nThis proposal describes a mechanism for configuring notification routing when tool calls complete. Using this mechanism:\n\n- Clients can specify where and how to receive notifications about tool call results\n- Servers can deliver notifications through transport-appropriate mechanisms\n- Clients can configure triggers based on tool call outcomes (success, failure, timeout)\n- Notifications work seamlessly with resumable requests when both features are enabled\n\n## Motivation\n\n- **Enabling asynchronous tool result delivery**\n    - Currently, clients must maintain active connections to receive tool call results\n    - There is no standard way to configure alternative notification delivery mechanisms\n    - Long-running tools may complete after clients have disconnected\n    - Different transports have different notification capabilities that aren't being utilized\n- **Supporting flexible notification routing**\n    - Clients need to route different tool results to different endpoints\n    - Some results may require immediate notification while others can be batched\n    - Transport-specific notification mechanisms (e.g., Unix signals for STDIO, webhooks for HTTP) need a unified configuration approach\n\n## Specification\n\n### 1. Capability negotiation\n\nServers supporting notification routing **MUST** declare their supported route types, along the fact they support notification, via capability negotiation:\n\n```ts\ninterface ServerCapabilities {\n  ...\n  notificationConfig?: {\n    supportedRouteTypes: string[];\n  };\n}\n```\n\n### 2. Client request\n\nClients **MAY** advertise a `notificationConfig` capability. When making a `tools/call` request, clients **MAY** include a `notificationConfig` parameter to request notification routing:\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": \"123\",\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"data_analysis\",\n    \"arguments\": { ... },\n    \"notificationConfig\": {\n      \"routes\": [\n        {\n          \"id\": \"primary\",\n          \"type\": \"webhook\",\n          \"endpoint\": \"https://example.com/notifications\",\n          \"triggers\": [\"completed\", \"failed\"]\n        }\n      ]\n    }\n  }\n}\n```\n\nThe `routes` array defines prioritized routes. The server selects, for each trigger, the first supported route it can deliver to. Servers **MUST** validate that all requested route types are supported and **MUST** reject the request with an error if unsupported types are used.\n\n### 3. Acknowledgement \n\nServers that support `notificationConfig` **MUST** acknowledge the configuration:\n    \n```json\n    {\n      \"jsonrpc\": \"2.0\",\n      \"method\": \"notifications/config/acknowledged\",\n      \"params\": {\n        \"requestId\": \"123\",\n        \"acceptedRoutes\": [\"primary\"]\n      }\n    }\n```    \n\n### Trigger Types\n\nThe following trigger types are defined:\n\n- `completed` — Tool call completed successfully\n- `failed` — Tool call failed with an error\n- `timeout` — Tool call exceeded time limit\n- `cancelled` — Tool call was cancelled\n- `streaming` — Tool call emitted a streaming response (e.g., via events or chunks)\n\nTrigger types are extensible. Additional types may be introduced in future SEPs.\n\n### Server Behavior\n\nWhen a configured trigger fires, the server:\n\n- Selects the first route (by priority) that it supports and can deliver on\n- Sends the notification using the configured transport and payload format\n- Optionally also delivers the result to the client if still connected\n\nIf no supported route is available for a given trigger, the server **MAY** silently drop the notification or include an error in the final result. It **MUST** do one of the two.\n\n### Notification Delivery Semantics\n\nTransport-specific behavior for each `type` (e.g., webhook, signal) will be defined in separate SEPs.\n\nServers **SHOULD** implement:\n- Retry policies for transient errors\n- Rate limiting to protect endpoints\n- Filtering or masking of sensitive data if necessary\n\n### Example Flow\n\n```mermaid\nsequenceDiagram\n    participant Client\n    participant Server\n    participant Tool\n    participant NotificationEndpoint as Notification Endpoint\n\n    Note over Client,Server: Client advertises notificationConfig capability\n\n    Client-\u003e\u003eServer: tools/call with notificationConfig\n    Server-\u003e\u003eTool: Execute tool\n\n    alt Tool Success\n        Tool-\u003e\u003eServer: Result\n        Note over Server: Trigger \"completed\"\n        Server-\u003e\u003eNotificationEndpoint: Send notification\n        Server-\u003e\u003eClient: Tool result (if connected)\n    else Tool Failure\n        Tool-\u003e\u003eServer: Error\n        Note over Server: Trigger \"failed\"\n        Server-\u003e\u003eNotificationEndpoint: Send notification\n        Server-\u003e\u003eClient: Error (if connected)\n    else Tool Timeout\n        Note over Server: Trigger \"timeout\"\n        Server-\u003e\u003eNotificationEndpoint: Send notification\n        Server-\u003e\u003eClient: Timeout (if connected)\n    end\n\n    Note over Client,NotificationEndpoint: Notifications are sent even if client is disconnected\n```\n\n## Rationale\n\nThe above specification addresses the issues outlined in the Motivation:\n\n- The `notificationConfig` parameter provides a standard way to configure notifications across all transports\n- The route-based system allows flexible notification delivery without prescribing specific mechanisms\n- Trigger types provide a consistent way to specify when notifications should be sent\n- The design is extensible to support transport-specific notification methods\n\n## Transport-Specific Considerations\n\nWhile the core specification is transport-agnostic, implementations may support transport-appropriate notification mechanisms. Each route `type` must be separately specified:\n\n| Type     | Transport     | SEP                 |\n|----------|---------------|---------------------|\n| webhook  | HTTP          | (future SEP)        |\n| signal   | STDIO         | (future SEP)        |\n| message  | WebSocket     | (future SEP)        |\n\n## Future Work\n\n- **Advanced triggers**\n    - Conditional triggers based on result content\n    - Time-based triggers\n    - Aggregate triggers across multiple tool calls\n- **Delivery guarantees**\n    - Retry policies\n    - Delivery confirmation\n    - Dead letter queues\n- **Security enhancements**\n    - Notification authentication\n    - Encrypted payloads\n    - Rate limiting\n\n## Alternatives\n\n- **Server-side configuration only**\nRejected because it reduces flexibility and requires server administrators to manage client-specific configurations.\n- **Extension of progress notifications**\nRejected because progress notifications serve a different purpose and have different delivery requirements.\n- **Transport-specific specifications**\nRejected because it would fragment the ecosystem and make it harder to build transport-agnostic tools.\n\n## Backwards Compatibility\n\nThis feature is fully backward compatible:\n\n- Clients must opt in via the `notificationConfig` capability\n- The configuration parameter is optional\n- Servers that don't support the feature will ignore the configuration\n- Existing tool call behavior remains unchanged\n\n## Security Implications\n\n- Notification endpoints must be validated by servers\n- Authentication credentials in configurations must be handled securely\n- Rate limiting should be implemented to prevent abuse\n- Sensitive data may need to be filtered from notifications based on security policies","author":{"url":"https://github.com/Joffref","@type":"Person","name":"Joffref"},"datePublished":"2025-07-17T15:06:18.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":13},"url":"https://github.com/992/modelcontextprotocol/issues/992"}