---
title: "Proxy Server"
description: "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.

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

## 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

```python
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

<ParamField path="backend_transport" type="string" required>
  Type of backend transport: "sqs", "sns_sqs", "webhook", or "hybrid"
</ParamField>

<ParamField path="backend_config" type="object" required>
  Configuration object for the selected backend transport
</ParamField>

<ParamField path="backend_clients" type="dict">
  AWS clients or other backend-specific clients needed by the transport
</ParamField>

<ParamField path="port" type="int" default="8080">
  Port for the proxy server to listen on
</ParamField>

<ParamField path="auth_token" type="string">
  Optional authentication token for client connections
</ParamField>

## Running the Proxy

### Command Line
```bash
# 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
```bash
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:

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

## Key Limitation

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

### 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](https://github.com/bh-rat/asyncmcp/blob/main/examples/proxy_sqs.py)
- [Proxy with Webhook Backend](https://github.com/bh-rat/asyncmcp/blob/main/examples/proxy_webhook.py)
- [Multi-Backend Proxy](https://github.com/bh-rat/asyncmcp/blob/main/examples/proxy_multi.py)