Webhook Transport

HTTP webhook transport for asyncmcp - web-native async messaging

Overview

The Webhook transport provides HTTP-based asynchronous messaging, perfect for web services and microservice architectures. It uses standard HTTP POST requests for communication without requiring cloud provider dependencies.

Webhook transport uses HTTP POST requests where the client sends requests to server endpoints and provides a webhook URL for receiving async responses.

Examples

View complete working examples in the GitHub repository:

• Webhook Server Example
• Webhook Client Example

Quick Start

Basic Usage

# Server (FastAPI)
from asyncmcp.webhook import WebhookSessionManager
from fastapi import FastAPI, Request

app = FastAPI()
manager = WebhookSessionManager(mcp_app)

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

# Client
from asyncmcp.webhook import webhook_client
from asyncmcp import WebhookClientConfig

config = WebhookClientConfig(
    server_url="https://api.example.com/mcp/request"
)

async with webhook_client(config, webhook_path="/webhook") as client:
    async with ClientSession(client.read, client.write) as session:
        # Webhook URL provided automatically in initialize
        await session.initialize()

Configuration

Server Configuration

Class: WebhookServerConfig

timeout_seconds · float · default: "30.0"

HTTP timeout for sending webhooks to clients.

max_retries · int · default: "0"

Number of retry attempts for failed webhook deliveries (default: no retries).

transport_timeout_seconds · float

Optional overall transport timeout.

Client Configuration

Class: WebhookClientConfig

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

URL of the server’s HTTP endpoint.

Example: https://api.example.com/mcp/request

timeout_seconds · float · default: "30.0"

HTTP request timeout in seconds.

max_retries · int · default: "0"

Number of retry attempts for failed requests (default: no retries).

client_id · string

Unique client identifier. Auto-generated if not provided.

transport_timeout_seconds · float

Optional overall transport timeout.

Note: The webhook URL is provided via the _meta field in the initialize request and is handled automatically by the client.