Proxy Server

Bridge standard MCP clients to async transports without client modifications

Overview

The asyncmcp proxy bridges standard MCP transports (StreamableHTTP/stdio) to asyncmcp’s asynchronous transports (SQS, SNS+SQS, Webhook). This enables existing MCP clients to connect to services running on async transports without modification.

The proxy exposes a standard MCP StreamableHTTP endpoint and forwards requests to configured async backend transports, streaming responses back via Server-Sent Events (SSE).

When to Use

✅ Use the proxy when:

• Existing MCP clients need to connect to async transport servers
• Gradual migration from sync to async transports
• Standard clients (Claude, Cursor) need async backend access

❌ Skip the proxy when:

• Building new clients with direct async transport support
• Both client and server support the same async transport
• Low-latency requirements (adds proxy overhead)

Quick Start

Basic Usage

from asyncmcp.proxy import create_proxy_server
from asyncmcp.sqs.utils import SqsClientConfig
import boto3

# Configure backend
backend_config = SqsClientConfig(
    read_queue_url="https://sqs.region.amazonaws.com/123/requests",
    response_queue_url="https://sqs.region.amazonaws.com/123/responses"
)

# Create and run proxy
proxy = create_proxy_server(
    backend_transport="sqs",
    backend_config=backend_config,
    backend_clients={"sqs_client": boto3.client("sqs")},
    port=8080
)

await proxy.run()

# Clients connect to http://localhost:8080/mcp

Configuration

backend_transport · string · required

Type of backend transport: “sqs”, “sns_sqs”, “webhook”, or “hybrid”

backend_config · object · required

Configuration object for the selected backend transport

backend_clients · dict

AWS clients or other backend-specific clients needed by the transport

port · int · default: "8080"

Port for the proxy server to listen on

auth_token · string

Optional authentication token for client connections

Running the Proxy

Command Line

# Run with SQS backend
python -m asyncmcp.proxy --backend sqs --port 8080

# Run with authentication
python -m asyncmcp.proxy --backend sqs --auth-token "secret"

Docker

docker run -p 8080:8080 \
  -e BACKEND_TRANSPORT=sqs \
  -e AWS_REGION=us-east-1 \
  asyncmcp-proxy:latest

Client Connection

Standard MCP clients connect using StreamableHTTP:

const client = new MCPClient({
    transport: {
        type: "streamable-http",
        url: "http://localhost:8080/mcp"
    }
});

Key Limitation

Session Correlation Challenge: The proxy has limited support for multiple concurrent sessions from the same proxy instance when using async transports.

The Problem

• Session IDs are generated by the server, not the client
• With async transports, responses arrive out of order
• Can’t reliably match initialize responses to proxy sessions

Impact

• Each proxy session needs its own backend connection
• Can’t share a single queue across multiple sessions
• Resource usage scales with concurrent sessions

Workaround

Use session affinity to route clients to the same proxy instance, or implement dynamic queue creation per session.

Examples

View complete working examples in the GitHub repository:

• Proxy with SQS Backend
• Proxy with Webhook Backend
• Multi-Backend Proxy