Skip to main content

​
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:

​
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.
⌘I