mcp-proxy-for-aws MCP工具

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

---

Installation

Using PyPi

```bash

Build the Docker image

docker build -t mcp-proxy-for-aws . ```

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

Using the pre-built public ECR image:

{
  "mcpServers": {
    "<mcp server name>": {
      "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",
        "<SigV4 MCP endpoint URL>"
      ],
      "env": {}
    }
  }
}

Or using a locally built image:

{
  "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": {}
    }
  }
}

---

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

---

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

Configuration Parameters

Optional Environment Variables

Set the environment variables for the MCP Proxy for AWS:

```bash

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):**

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

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

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, ...)

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.

Troubleshooting