Preamble

Authors: Mathis Joffre

Abstract

This proposal describes a mechanism for configuring notification routing when tool calls complete. Using this mechanism:

• Clients can specify where and how to receive notifications about tool call results
• Servers can deliver notifications through transport-appropriate mechanisms
• Clients can configure triggers based on tool call outcomes (success, failure, timeout)
• Notifications work seamlessly with resumable requests when both features are enabled

Motivation

• Enabling asynchronous tool result delivery
  • Currently, clients must maintain active connections to receive tool call results
  • There is no standard way to configure alternative notification delivery mechanisms
  • Long-running tools may complete after clients have disconnected
  • Different transports have different notification capabilities that aren't being utilized
• Supporting flexible notification routing
  • Clients need to route different tool results to different endpoints
  • Some results may require immediate notification while others can be batched
  • Transport-specific notification mechanisms (e.g., Unix signals for STDIO, webhooks for HTTP) need a unified configuration approach

Specification

1. Capability negotiation

Servers supporting notification routing MUST declare their supported route types, along the fact they support notification, via capability negotiation:

interface ServerCapabilities {
  ...
  notificationConfig?: {
    supportedRouteTypes: string[];
  };
}

2. Client request

Clients MAY advertise a notificationConfig capability. When making a tools/call request, clients MAY include a notificationConfig parameter to request notification routing:

{
  "jsonrpc": "2.0",
  "id": "123",
  "method": "tools/call",
  "params": {
    "name": "data_analysis",
    "arguments": { ... },
    "notificationConfig": {
      "routes": [
        {
          "id": "primary",
          "type": "webhook",
          "endpoint": "https://example.com/notifications",
          "triggers": ["completed", "failed"]
        }
      ]
    }
  }
}

The 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.

3. Acknowledgement

Servers that support notificationConfig MUST acknowledge the configuration:

    {
      "jsonrpc": "2.0",
      "method": "notifications/config/acknowledged",
      "params": {
        "requestId": "123",
        "acceptedRoutes": ["primary"]
      }
    }

Trigger Types

The following trigger types are defined:

• completed — Tool call completed successfully
• failed — Tool call failed with an error
• timeout — Tool call exceeded time limit
• cancelled — Tool call was cancelled
• streaming — Tool call emitted a streaming response (e.g., via events or chunks)

Trigger types are extensible. Additional types may be introduced in future SEPs.

Server Behavior

When a configured trigger fires, the server:

• Selects the first route (by priority) that it supports and can deliver on
• Sends the notification using the configured transport and payload format
• Optionally also delivers the result to the client if still connected

If 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.

Notification Delivery Semantics

Transport-specific behavior for each type (e.g., webhook, signal) will be defined in separate SEPs.

Servers SHOULD implement:

• Retry policies for transient errors
• Rate limiting to protect endpoints
• Filtering or masking of sensitive data if necessary

Example Flow

sequenceDiagram
    participant Client
    participant Server
    participant Tool
    participant NotificationEndpoint as Notification Endpoint

    Note over Client,Server: Client advertises notificationConfig capability

    Client->>Server: tools/call with notificationConfig
    Server->>Tool: Execute tool

    alt Tool Success
        Tool->>Server: Result
        Note over Server: Trigger "completed"
        Server->>NotificationEndpoint: Send notification
        Server->>Client: Tool result (if connected)
    else Tool Failure
        Tool->>Server: Error
        Note over Server: Trigger "failed"
        Server->>NotificationEndpoint: Send notification
        Server->>Client: Error (if connected)
    else Tool Timeout
        Note over Server: Trigger "timeout"
        Server->>NotificationEndpoint: Send notification
        Server->>Client: Timeout (if connected)
    end

    Note over Client,NotificationEndpoint: Notifications are sent even if client is disconnected

Rationale

The above specification addresses the issues outlined in the Motivation:

• The notificationConfig parameter provides a standard way to configure notifications across all transports
• The route-based system allows flexible notification delivery without prescribing specific mechanisms
• Trigger types provide a consistent way to specify when notifications should be sent
• The design is extensible to support transport-specific notification methods

Transport-Specific Considerations

While the core specification is transport-agnostic, implementations may support transport-appropriate notification mechanisms. Each route type must be separately specified:

Future Work

• Advanced triggers
  • Conditional triggers based on result content
  • Time-based triggers
  • Aggregate triggers across multiple tool calls
• Delivery guarantees
  • Retry policies
  • Delivery confirmation
  • Dead letter queues
• Security enhancements
  • Notification authentication
  • Encrypted payloads
  • Rate limiting

Alternatives

• Server-side configuration only
  Rejected because it reduces flexibility and requires server administrators to manage client-specific configurations.
• Extension of progress notifications
  Rejected because progress notifications serve a different purpose and have different delivery requirements.
• Transport-specific specifications
  Rejected because it would fragment the ecosystem and make it harder to build transport-agnostic tools.

Backwards Compatibility

This feature is fully backward compatible:

• Clients must opt in via the notificationConfig capability
• The configuration parameter is optional
• Servers that don't support the feature will ignore the configuration
• Existing tool call behavior remains unchanged

Security Implications

• Notification endpoints must be validated by servers
• Authentication credentials in configurations must be handled securely
• Rate limiting should be implemented to prevent abuse
• Sensitive data may need to be filtered from notifications based on security policies