> ## Documentation Index
> Fetch the complete documentation index at: https://asyncmcp.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

<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 theme={null}
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 theme={null}
# 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 theme={null}
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 theme={null}
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)