Skip to main content

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