StreamableHTTP + Webhook Transport

Combine SSE streaming with webhook delivery for mixed sync/async operations

Overview

The StreamableHTTP + Webhook transport combines MCP’s StreamableHTTP (with Server-Sent Events) for immediate responses with webhook delivery for long-running async operations. This provides the best of both worlds - real-time streaming for quick operations and webhook callbacks for async processing.

This transport allows selective routing where specific tools use webhook delivery while others use SSE streaming, all within a single session.

Examples

View complete working examples in the GitHub repository:

• StreamableHTTP + Webhook Server Example
• StreamableHTTP + Webhook Client Example

Quick Start

Basic Usage

# Server with selective routing
from asyncmcp.streamable_http_webhook import (
    StreamableHTTPWebhookSessionManager,
    StreamableHTTPWebhookConfig
)

# Configure the transport
config = StreamableHTTPWebhookConfig()

# Define which tools use webhook
webhook_tools = {"process_batch", "analyze_large_dataset"}

manager = StreamableHTTPWebhookSessionManager(
    mcp_app,
    config,
    webhook_tools=webhook_tools
)

# FastAPI integration
@app.post("/mcp")
async def handle_mcp(request: Request):
    return await manager.handle_request(request)

# Client
from asyncmcp.streamable_http_webhook import (
    streamable_http_webhook_client,
    StreamableHTTPWebhookClientConfig
)

config = StreamableHTTPWebhookClientConfig(
    server_url="http://api.example.com/mcp",
    webhook_url="http://client.example.com/webhook"
)

async with streamable_http_webhook_client(config) as (read_stream, write_stream, client):
    # Use the streams for MCP communication
    # Quick tool - uses SSE
    # Async tool - uses webhook
    pass

Configuration

Server Configuration

Class: StreamableHTTPWebhookConfig

json_response · boolean · default: "false"

Use JSON responses instead of SSE streaming. Set to false for SSE.

timeout_seconds · float · default: "30.0"

HTTP timeout for SSE responses.

webhook_timeout · float · default: "30.0"

Timeout for webhook delivery attempts.

webhook_max_retries · int · default: "1"

Maximum retry attempts for failed webhook deliveries.

transport_timeout_seconds · float

Optional overall transport timeout.

Note: The webhook_tools set is configured at the session manager level, not in the config.

Client Configuration

Class: StreamableHTTPWebhookClientConfig

server_url · string · default: "http://localhost:8000/mcp"

StreamableHTTP endpoint URL.

Example: http://api.example.com/mcp

webhook_url · string · default: "http://localhost:8001/webhook"

Webhook URL for async responses.

Example: http://client.example.com/webhook

timeout_seconds · float · default: "30.0"

HTTP request timeout in seconds.

max_retries · int · default: "1"

Number of retry attempts for failed requests.

client_id · string

Unique client identifier. Auto-generated if not provided.

transport_timeout_seconds · float

Optional overall transport timeout.