Mcp Proxy For Aws

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, Kiro CLI) and MCP servers on AWS. (See [MCP Proxy](#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](#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, Kiro 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 Kiro 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@1.6.0 

Note: It is recommended to pin to a specific version (e.g., @1.6.0) to ensure reproducible behavior. Using @latest may pull in breaking changes. Check PyPI for the latest stable version.

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 

Using Docker

Docker images are published to the public AWS ECR registry.

You can use the pre-built image:

# Pull the latest image
docker pull public.ecr.aws/mcp-proxy-for-aws/mcp-proxy-for-aws:latest

# Or pull a specific version
docker pull public.ecr.aws/mcp-proxy-for-aws/mcp-proxy-for-aws:1.1.6

Or build the image locally:

# 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(s) to use. First profile is the default. Additional profiles enable per-call switching via aws_profile tool parameter (e.g., --profile prod-readonly dev staging) | Falls back to AWS_PROFILE if --profile and AWS_MCP_PROXY_PROFILES are not set |No | | --region | AWS region to use | Uses AWS_REGION environment variable if not set |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 | | --tool-timeout | Maximum seconds a tool call may take before being cancelled. When set, returns a graceful error to the agent instead of hanging indefinitely | 300 |No | | --skip-auth | Skip request signing when AWS credentials are unavailable instead of failing | False |No | | --disable-telemetry | Disables telemetry data collection | False |No |

Optional Environment Variables

Set the environment variables for the MCP Proxy for AWS:

# Credentials through profile
export AWS_PROFILE=

# Credentials through parameters
export AWS_ACCESS_KEY_ID=
export AWS_SECRET_ACCESS_KEY=
export AWS_SESSION_TOKEN=

# AWS Region
export AWS_REGION=

# Multi-profile switching (alternative to --profile flag, useful for plugin integration)
export AWS_MCP_PROXY_PROFILES="prod-readonly dev staging"

> Note: AWS_MCP_PROXY_PROFILES takes precedence over --profile / AWS_PROFILE when set.

Multi-account access

The proxy supports per-call AWS profile switching, allowing agents to work across multiple accounts without restarting.

Configuration:

# Via CLI flag (first profile is default, rest are switchable)
mcp-proxy-for-aws https://aws-mcp.us-east-1.api.aws/mcp --profile prod-readonly dev staging

# Via environment variable (same behavior, for plugin integration)
AWS_MCP_PROXY_PROFILES="prod-readonly dev staging" mcp-proxy-for-aws https://aws-mcp.us-east-1.api.aws/mcp

How it works:

• The proxy injects an aws_profile parameter into auth-requiring tools
• The agent can pass aws_profile on any call to route it through a specific profile's credentials
• If aws_profile is omitted, the default (first) profile is used
• Invalid profiles are rejected with an error listing allowed values
• Each non-default profile gets its own dedicated connection to the backend

Example MCP config (Kiro):

{
  "mcpServers": {
    "aws": {
      "command": "uvx",
      "args": ["mcp-proxy-for-aws@1.6.0", "https://aws-mcp.us-east-1.api.aws/mcp"],
      "env": {
        "AWS_MCP_PROXY_PROFILES": "prod-readonly dev staging"
      }
    }
  }
}

Setup Examples

Add the following configuration to your MCP client config file (e.g., for Kiro CLI, edit ~/.kiro/settings/mcp.json): Note Add your own endpoint by replacing ``

Running from local - using uv

{
  "mcpServers": {
    "": {
      "disabled": false,
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp_proxy_for_aws",
        "run",
        "server.py",
        "",
        "--service",
        "",
        "--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

Using the pre-built public ECR image:

{
  "mcpServers": {
    "": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--volume",
        "/full/path/to/.aws:/app/.aws:ro",
        "public.ecr.aws/mcp-proxy-for-aws/mcp-proxy-for-aws:latest",
        ""
      ],
      "env": {}
    }
  }
}

Or using a locally built image:

{
  "mcpServers": {
    "": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "--volume",
        "/full/path/to/.aws:/app/.aws:ro",
        "mcp-proxy-for-aws",
        ""
      ],
      "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.

By default, the library resolves AWS credentials automatically from the standard boto3 credential chain (environment variables, shared credentials file, etc.). You can optionally pass credentials programmatically via the credentials parameter. When provided, these take precedence over the aws_profile parameter. Note that aws_region must be explicitly specified when using credentials.

from botocore.credentials import Credentials
from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client

creds = Credentials(access_key="...", secret_key="...", token="...")

mcp_client = aws_iam_streamablehttp_client(
    endpoint=mcp_url,
    aws_region=region,
    aws_service=service,
    credentials=creds,  # Optional: explicitly pass AWS credentials
)

Injecting Metadata

You can inject metadata into the MCP _meta field on every request using the metadata parameter. This is useful for passing additional context to the server that cannot be sent as HTTP headers due to size limits.

from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client

mcp_client = aws_iam_streamablehttp_client(
    endpoint=mcp_url,
    aws_region=region,
    aws_service=service,
    metadata={
        "custom/session-context": "my-value",
        "custom/tracking-id": "abc-123",
    },
)

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 un

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [aws](https://github.com/aws)
- **Source:** [aws/mcp-proxy-for-aws](https://github.com/aws/mcp-proxy-for-aws)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.