SQS Transport

AWS Simple Queue Service transport for asyncmcp - reliable queue-based async messaging

Overview

SQS transport uses direct queue-to-queue communication where the server listens on a request queue and sends responses to client-specific response queues.

Examples

View complete working examples in the GitHub repository:

• SQS Server Example
• SQS Client Example
• LocalStack Setup

Quick Start

Basic Usage

# Server
from asyncmcp.sqs import sqs_server
from asyncmcp import SqsServerConfig

config = SqsServerConfig(
    read_queue_url="https://sqs.region.amazonaws.com/account/requests"
)

async with sqs_server(config, sqs_client) as (read, write):
    await app.run(read, write, init_options)

# Client
from asyncmcp.sqs import sqs_client
from asyncmcp import SqsClientConfig

config = SqsClientConfig(
    read_queue_url="https://sqs.region.amazonaws.com/account/requests",
    response_queue_url="https://sqs.region.amazonaws.com/account/responses"
)

async with sqs_client(config, sqs_client) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()

Configuration

Server Configuration

Class: SqsServerConfig

read_queue_url · string · required

URL of the SQS queue where the server receives requests.

Example: https://sqs.us-east-1.amazonaws.com/123456789/mcp-requests

max_messages · int · default: "10"

Maximum messages to retrieve per poll (1-10).

wait_time_seconds · int · default: "20"

Long polling duration (0-20). Use 20 for cost optimization.

visibility_timeout_seconds · int · default: "30"

Seconds a message remains invisible after retrieval.

poll_interval_seconds · float · default: "5.0"

Seconds between queue polling attempts. Lower values reduce latency but increase costs.

message_attributes · dict

Custom attributes to include with messages.

transport_timeout_seconds · float

Optional overall transport timeout.

Client Configuration

Class: SqsClientConfig

read_queue_url · string · required

URL of the server’s request queue.

Example: https://sqs.us-east-1.amazonaws.com/123456789/mcp-requests

response_queue_url · string · required

URL of the client’s response queue. Can be pre-created or dynamically generated.

Example: https://sqs.us-east-1.amazonaws.com/123456789/mcp-responses

client_id · string

Unique client identifier. Auto-generated if not provided.

message_attributes · dict

Custom attributes to include with messages.

transport_timeout_seconds · float

Optional overall transport timeout.