AWS MCP Proxy Server

What is AWS MCP Proxy Server about?

Provides a lightweight bridge that lets AI assistants, developer CLIs, and custom agent frameworks communicate with MCP servers secured with AWS IAM credentials. It abstracts away the complexity of SigV4 request signing, allowing seamless interaction without writing custom authentication code.

How to use AWS MCP Proxy Server?

• As a proxy: Run the server locally with uvx mcp-proxy-for-aws@latest <endpoint> or via Docker (docker run --rm -v $HOME/.aws:/app/.aws:ro mcp-proxy-for-aws <endpoint>). Configure your MCP client (e.g., Claude Desktop, Amazon Q CLI) to point to the proxy.
• As a library: Install with pip install mcp-proxy-for-aws. Import aws_iam_streamablehttp_client and pass it to frameworks such as LangChain, LlamaIndex, Strands Agents, or Microsoft Agent Framework to obtain an authenticated MCP session.
• Configuration: Supply endpoint URL, optional --service, --region, --profile, metadata key‑value pairs, read‑only flag, retry count, timeouts, and log level via command‑line arguments or environment variables (AWS_PROFILE, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_REGION).

Key Features of AWS MCP Proxy Server

• Automatic SigV4 signing using local AWS credentials.
• Dual mode operation: standalone proxy (CLI/Docker) and importable Python library.
• Flexible configuration: service inference, region/profile overrides, custom metadata injection.
• Read‑only mode to restrict tool usage that requires write permissions.
• Retry, timeout, and logging controls for robust production use.
• Pre‑built Docker image for containerized deployments.
• Comprehensive examples for LangChain, LlamaIndex, Strands Agents, and Microsoft Agent Framework.

Use Cases of AWS MCP Proxy Server

• Connecting consumer AI tools (Claude Desktop, Amazon Q Developer CLI) to IAM‑secured MCP endpoints without native support.
• Building enterprise AI agents that need tool discovery and execution on MCP servers while leveraging existing AWS IAM policies.
• Integrating MCP‑based toolsets into Python AI pipelines (LangChain, LlamaIndex) with minimal code changes.
• Running a centralized proxy in a container to serve multiple developers or services within a VPC.

FAQ from the AWS MCP Proxy Server

Q: Which AWS credentials are used? A: The proxy reads credentials from the AWS CLI configuration, environment variables, or the instance/profile IAM role. You can explicitly set a profile with --profile.

Q: How do I specify the AWS service for SigV4 signing? A: The --service flag overrides automatic inference. Required when the service name cannot be derived from the endpoint URL.

Q: What does the --read-only flag do? A: It disables tools that require write permissions, exposing only read‑only capabilities annotated with readOnlyHint=true.

Q: Can I run the proxy in Docker? A: Yes. Build the image with docker build -t mcp-proxy-for-aws . and run it, mounting your .aws folder to provide credentials.

Q: How do I integrate with LangChain? A: Import aws_iam_streamablehttp_client, create a client, and use it to build a ClientSession that LangChain can consume for tool loading.

Q: What timeout values are recommended? A: Defaults are 180 s overall, 60 s connect, 120 s read, and 180 s write, but they can be tuned via --timeout, --connect-timeout, --read-timeout, and --write-timeout.

Q: How can I troubleshoot authentication errors? A: Ensure the correct --service is set, verify that valid IAM credentials are available, and check that the endpoint matches the service you are signing for.

MCP Proxy for AWS

Overview

The MCP Proxy for AWS package provides two ways to connect AI applications to MCP servers on AWS:

1. Using it as a proxy - It becomes a lightweight, client-side bridge between MCP clients (AI assistants like Claude Desktop, Amazon Q Developer CLI) and MCP servers on AWS. (See MCP Proxy)
2. Using it as a library - Programmatically connect popular AI agent frameworks (LangChain, LlamaIndex, Strands Agents, etc.) to MCP servers on AWS. (See Programmatic Access)

When Do You Need This Package?

• You want to connect to MCP servers on AWS (e.g., using Amazon Bedrock AgentCore) that use AWS IAM authentication (SigV4) instead of OAuth
• You're using MCP clients (like Claude Desktop, Amazon Q Developer CLI) that don't natively support AWS IAM authentication
• You're building AI agents with popular frameworks like LangChain, Strands Agents, LlamaIndex, etc., that need to connect to MCP servers on AWS
• You want to avoid building custom SigV4 request signing logic yourself

How This Package Helps

The Problem: The official MCP specification supports OAuth-based authentication, but MCP servers on AWS can also use AWS IAM authentication (SigV4). Standard MCP clients don't know how to sign requests with AWS credentials.

The Solution: This package bridges that gap by:

• Handling SigV4 authentication automatically - Uses your local AWS credentials (from AWS CLI, environment variables, or IAM roles) to sign all MCP requests using SigV4
• Providing seamless integration - Works with existing MCP clients and frameworks
• Eliminating custom code - No need to build your own MCP client with SigV4 signing logic

Which Feature Should I Use?

Use as a proxy if you want to:

• Connect MCP clients like Claude Desktop or Amazon Q Developer CLI to MCP servers on AWS with IAM credentials
• Add MCP servers on AWS to your AI assistant's configuration
• Use a command-line tool that runs as a bridge between your MCP client and AWS

Use as a library if you want to:

• Build AI agents programmatically using popular frameworks like LangChain, Strands Agents, or LlamaIndex
• Integrate AWS IAM-secured MCP servers directly into your Python applications
• Have fine-grained control over the MCP session lifecycle in your code

Prerequisites

• Install Python 3.10+
• Install the uv package manager
• AWS credentials configured (via AWS CLI, environment variables, or IAM roles)
• (Optional, for docker users) Install Docker Desktop

---

MCP Proxy

The MCP Proxy serves as a lightweight, client-side bridge between MCP clients (AI assistants and developer tools) and IAM-secured MCP servers on AWS. The proxy handles SigV4 authentication using local AWS credentials and provides dynamic tool discovery.

Installation

Using PyPi

# Run the server
uvx mcp-proxy-for-aws@latest <SigV4 MCP endpoint URL>

Note: The first run may take tens of seconds as uvx downloads and caches dependencies. Subsequent runs will start in seconds. Actual startup time depends on your network and hardware.

Using a local repository

git clone https://github.com/aws/mcp-proxy-for-aws.git
cd mcp-proxy-for-aws
uv run mcp_proxy_for_aws/server.py <SigV4 MCP endpoint URL>

Using Docker

# Build the Docker image
docker build -t mcp-proxy-for-aws .

Configuration Parameters

Parameter	Description	Default	Required
endpoint	MCP endpoint URL (e.g., https://your-service.us-east-1.amazonaws.com/mcp)	N/A	Yes
---	---	---	---
--service	AWS service name for SigV4 signing, if omitted we try to infer this from the url	Inferred from endpoint if not provided	No
--profile	AWS profile for AWS credentials to use	Uses AWS_PROFILE environment variable if not set	No
--region	AWS region to use	Uses AWS_REGION environment variable if not set, defaults to us-east-1	No
--metadata	Metadata to inject into MCP requests as key=value pairs (e.g., --metadata KEY1=value1 KEY2=value2)	AWS_REGION is automatically injected based on --region if not provided	No
--read-only	Disable tools which may require write permissions (tools which DO NOT require write permissions are annotated with readOnlyHint=true)	False	No
--retries	Configures number of retries done when calling upstream services, setting this to 0 disables retries.	0	No
--log-level	Set the logging level (DEBUG/INFO/WARNING/ERROR/CRITICAL)	INFO	No
--timeout	Set desired timeout in seconds across all operations	180	No
--connect-timeout	Set desired connect timeout in seconds	60	No
--read-timeout	Set desired read timeout in seconds	120	No
--write-timeout	Set desired write timeout in seconds	180	No

Optional Environment Variables

Set the environment variables for the MCP Proxy for AWS:

# Credentials through profile
export AWS_PROFILE=<aws_profile>

# Credentials through parameters
export AWS_ACCESS_KEY_ID=<access_key_id>
export AWS_SECRET_ACCESS_KEY=<secret_access_key>
export AWS_SESSION_TOKEN=<session_token>

# AWS Region
export AWS_REGION=<aws_region>

Setup Examples

Add the following configuration to your MCP client config file (e.g., for Amazon Q Developer CLI, edit ~/.aws/amazonq/mcp.json): Note Add your own endpoint by replacing <SigV4 MCP endpoint URL>

Running from local - using uv

{
  "mcpServers": {
    "<mcp server name>": {
      "disabled": false,
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp_proxy_for_aws",
        "run",
        "server.py",
        "<SigV4 MCP endpoint URL>",
        "--service",
        "<your service code>",
        "--profile",
        "default",
        "--region",
        "us-east-1",
        "--read-only",
        "--log-level",
        "INFO",
      ]
    }
  }
}

[!NOTE] Cline users should not use --log-level argument because Cline checks the log messages in stderr for text "error" (case insensitive).

Using Docker

{
  "mcpServers": {
    "<mcp server name>": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "--volume",
        "/full/path/to/.aws:/app/.aws:ro",
        "mcp-proxy-for-aws",
        "<SigV4 MCP endpoint URL>"
      ],
      "env": {}
    }
  }
}

---

Programmatic Access

The MCP Proxy for AWS enables programmatic integration of IAM-secured MCP servers into AI agent frameworks. The library provides authenticated transport layers that work with popular Python AI frameworks.

Integration Patterns

The library supports two integration patterns depending on your framework:

Pattern 1: Client Factory Integration

Use with: Frameworks that accept a factory function that returns an MCP client, e.g. Strands Agents, Microsoft Agent Framework. The aws_iam_streamablehttp_client is passed as a factory to the framework, which handles the connection lifecycle internally.

Example - Strands Agents:

from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client

mcp_client_factory = lambda: aws_iam_streamablehttp_client(
    endpoint=mcp_url,    # The URL of the MCP server
    aws_region=region,   # The region of the MCP server
    aws_service=service  # The underlying AWS service, e.g. "bedrock-agentcore"
)

with MCPClient(mcp_client_factory) as mcp_client:
    mcp_tools = mcp_client.list_tools_sync()
    agent = Agent(tools=mcp_tools, ...)

Example - Microsoft Agent Framework:

from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client

mcp_client_factory = lambda: aws_iam_streamablehttp_client(
    endpoint=mcp_url,    # The URL of the MCP server
    aws_region=region,   # The region of the MCP server
    aws_service=service  # The underlying AWS service, e.g. "bedrock-agentcore"
)

mcp_tools = MCPStreamableHTTPTool(name="MCP Tools", url=mcp_url)
mcp_tools.get_mcp_client = mcp_client_factory

async with mcp_tools:
    agent = ChatAgent(tools=[mcp_tools], ...)

Pattern 2: Direct MCP Session Integration

Use with: Frameworks that require direct access to the MCP sessions, e.g. LangChain, LlamaIndex. The aws_iam_streamablehttp_client provides the authenticated transport streams, which are then used to create an MCP ClientSession.

Example - LangChain:

from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client

mcp_client = aws_iam_streamablehttp_client(
    endpoint=mcp_url,    # The URL of the MCP server
    aws_region=region,   # The region of the MCP server
    aws_service=service  # The underlying AWS service, e.g. "bedrock-agentcore"
)

async with mcp_client as (read, write, session_id_callback):
    async with ClientSession(read, write) as session:
        mcp_tools = await load_mcp_tools(session)
        agent = create_langchain_agent(tools=mcp_tools, ...)

Example - LlamaIndex:

from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client

mcp_client = aws_iam_streamablehttp_client(
    endpoint=mcp_url,    # The URL of the MCP server
    aws_region=region,   # The region of the MCP server
    aws_service=service  # The underlying AWS service, e.g. "bedrock-agentcore"
)

async with mcp_client as (read, write, session_id_callback):
    async with ClientSession(read, write) as session:
        mcp_tools = await McpToolSpec(client=session).to_tool_list_async()
        agent = ReActAgent(tools=mcp_tools, ...)

Running Examples

Explore complete working examples for different frameworks in the ./examples/mcp-client directory:

Available examples:

• LangChain
• LlamaIndex
• Microsoft Agent Framework
• Strands Agents SDK

Run examples individually:

cd examples/mcp-client/[framework]  # e.g. examples/mcp-client/strands
uv run main.py

Installation

The client library is included when you install the package:

pip install mcp-proxy-for-aws

For development:

git clone https://github.com/aws/mcp-proxy-for-aws.git
cd mcp-proxy-for-aws
uv sync

---

Troubleshooting

Handling Authentication error - Invalid credentials

We try to autodetect the service from the url, sometimes this fails, ensure that --service is set correctly to the service you are attempting to connect to. Otherwise the SigV4 signing will not be able to be verified by the service you connect to, resulting in this error. Also ensure that you have valid IAM credentials on your machine before retrying.

Development & Contributing

For development setup, testing, and contribution guidelines, see:

• DEVELOPMENT.md - Development environment setup and testing
• CONTRIBUTING.md - How to contribute to this project

Resources to understand SigV4:

• SigV4 User Guide: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html
• SigV4 Signers: https://github.com/boto/botocore/blob/develop/botocore/signers.py
• SigV4a: https://github.com/aws-samples/sigv4a-signing-examples/blob/main/python/sigv4a_sign.py

License

Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. Licensed under the Apache License, Version 2.0 (the "License").

Disclaimer

LLMs are non-deterministic and they make mistakes, we advise you to always thoroughly test and follow the best practices of your organization before using these tools on customer facing accounts. Users of this package are solely responsible for implementing proper security controls and MUST use AWS Identity and Access Management (IAM) to manage access to AWS resources. You are responsible for configuring appropriate IAM policies, roles, and permissions, and any security vulnerabilities resulting from improper IAM configuration are your sole responsibility. By using this package, you acknowledge that you have read and understood this disclaimer and agree to use the package at your own risk.