MCP Proxy for AWS

1.3.0 · active · verified Thu Apr 16

The MCP Proxy for AWS is a Python library that serves as a lightweight, client-side bridge between Model Context Protocol (MCP) clients (such as AI assistants and developer tools) and IAM-secured MCP servers on AWS. It handles SigV4 authentication using local AWS credentials and provides dynamic tool discovery. The library is currently at version 1.3.0 and is actively maintained, with updates released as needed to support AWS services and the MCP specification.

Common errors

```
Error -32602: Invalid request parameters
```
cause This error often indicates a protocol mismatch or incorrect parameter formatting between the MCP client (e.g., an AI assistant) and the `mcp-proxy-for-aws` during tool or resource fetching. It can be due to a client expecting a different API version or a malformed request body.

fix Check the debug logs for more details on the malformed request. Ensure your MCP client is compatible with the `mcp-proxy-for-aws` version and the target MCP server's API. Consult the `mcp-proxy-for-aws` GitHub repository for known compatibility issues or updates.
```
Failed to connect to MCP server: Could not connect to the endpoint URL: "https://your-mcp-server.amazonaws.com/mcp"
```
cause The proxy cannot reach the specified MCP endpoint URL. This could be due to network issues, an incorrect URL, or the MCP server not being active or accessible from where the proxy is running.

fix Verify the `MCP_ENDPOINT_URL` is correct and the server is running. Check network connectivity (e.g., firewall rules, VPC configurations). Ensure that the proxy has the necessary permissions to access the network.
```
botocore.exceptions.ClientError: An error occurred (InvalidClientTokenId) when calling the GetCallerIdentity operation: The security token included in the request is invalid.
```
cause The AWS credentials configured for the proxy are invalid or expired, preventing successful SigV4 authentication with AWS.

fix Refresh your AWS credentials. Verify that `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` (if using temporary credentials) are correctly set, or that your AWS CLI profile is valid and has the necessary permissions.

Warnings

gotcha AWS credentials and region must be correctly configured. The proxy uses the standard boto3 credential chain (environment variables, shared credentials file, EC2 instance profiles, etc.). If not found, authentication will fail.
Fix: Ensure `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION` environment variables are set, or an AWS CLI profile is configured. For programmatic use with explicit credentials, ensure `aws_region` is always provided.
gotcha When using `mcp-proxy-for-aws` as a command-line tool, the `--region` argument defaults to `us-east-1` if not explicitly specified or inferred from environment variables. This can lead to connection issues if your MCP server is in a different region and `--region` is not set.
Fix: Always explicitly specify the `--region` parameter or ensure the `AWS_REGION` environment variable is set to match your MCP server's region when running the proxy via `uvx` or `python -m`.
deprecated The `awslabs.core-mcp-server` is deprecated. Its proxy/orchestration pattern is no longer necessary as modern MCP clients support multi-server configurations natively. This is distinct from `mcp-proxy-for-aws` but related in the MCP ecosystem, and users might confuse them.
Fix: If you were using `awslabs.core-mcp-server`, migrate to configuring individual MCP servers directly within your client. `mcp-proxy-for-aws` remains active for its specific purpose of SigV4 authentication.

Install

pip install mcp-proxy-for-aws Install with pip
uvx mcp-proxy-for-aws@latest <SigV4 MCP endpoint URL> Run as a proxy with uvx

Imports

McpProxy
```
from mcp_proxy_for_aws.mcp_proxy import McpProxy
```
For programmatic use as a library to interact with MCP servers.
run_server
```
from mcp_proxy_for_aws.server import run_server
```
For running the proxy server programmatically.

Quickstart

This quickstart demonstrates how to programmatically initialize the `McpProxy` client. It assumes AWS credentials (e.g., `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`) and the `MCP_ENDPOINT_URL` environment variable are set. The client handles SigV4 authentication automatically using the default boto3 credential chain.

import os
from mcp_proxy_for_aws.mcp_proxy import McpProxy

# Ensure AWS credentials and region are configured (e.g., via environment variables or ~/.aws/credentials)
# For programmatic use, you might explicitly pass them, but for quickstart, rely on boto3's default chain.
aws_region = os.environ.get('AWS_REGION', 'us-east-1')
mcp_endpoint_url = os.environ.get('MCP_ENDPOINT_URL', 'https://your-mcp-server.amazonaws.com/mcp')

try:
    # Initialize the MCP Proxy client
    proxy_client = McpProxy(endpoint=mcp_endpoint_url, region=aws_region)
    print(f"Initialized MCP Proxy for endpoint: {mcp_endpoint_url}")

    # Example: Discover tools (this would typically involve calling a method that hits the MCP server)
    # Note: The actual method for tool discovery might vary based on the MCP server implementation.
    # This is a placeholder for demonstrating client initialization.
    print("Attempting to discover tools (requires a live MCP server)...")
    # In a real scenario, you'd call methods like proxy_client.discover_tools() if available
    # or integrate with an AI agent framework.
    print("MCP Proxy client initialized successfully. Ready for agent integration.")

except Exception as e:
    print(f"Error initializing MCP Proxy: {e}")
    print("Please ensure 'MCP_ENDPOINT_URL' and AWS credentials/region are correctly configured.")

view raw JSON →