Metadata-Version: 2.4
Name: mcp-proxy-for-aws-multi
Version: 0.1.0
Summary: Multi-endpoint MCP Proxy for AWS with automatic tool merging
Project-URL: documentation, https://github.com/aws/aws-mcp-proxy/blob/main/README.md
Project-URL: repository, https://github.com/aws/mcp-proxy-for-aws.git
Project-URL: changelog, https://github.com/aws/aws-mcp-proxy/blob/main/CHANGELOG.md
Author: Amazon Web Services, MCP Proxy for AWS
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.10
Requires-Dist: boto3>=1.41.0
Requires-Dist: botocore[crt]>=1.41.0
Requires-Dist: fastmcp~=3.2.0
Description-Content-Type: text/markdown

# MCP Proxy for AWS (Multi-Endpoint)

## Overview

**mcp-proxy-for-aws-multi** is a multi-endpoint MCP proxy that connects AI applications to multiple MCP servers simultaneously. It automatically merges tools and resources from all endpoints into a single unified interface, with intelligent routing of calls to the correct backend.

Key features:
- **Multi-endpoint support** — connect to one or more MCP endpoints and get a merged tool/resource list
- **Automatic SigV4 signing** — AWS MCP endpoints (`.api.aws`) are signed automatically using your local credentials
- **Plain HTTP passthrough** — non-AWS endpoints (e.g. localhost) are connected without signing
- **Automatic tool routing** — tool calls are routed to the correct backend transparently

### When Do You Need This Package?

- You want to connect to **multiple MCP servers** (e.g., AWS MCP + a local UI server) through a single proxy
- You need **SigV4 authentication** for AWS MCP endpoints
- You want tools from multiple servers **merged automatically** without manual configuration

## Prerequisites

* [Python 3.10+](https://www.python.org/downloads/release/python-3100/)
* [uv package manager](https://docs.astral.sh/uv/getting-started/installation/)
* AWS credentials configured (for AWS MCP endpoints)

## Installation

```bash
# Install from PyPI
pip install mcp-proxy-for-aws-multi

# Or run directly with uvx
uvx mcp-proxy-for-aws-multi@latest <endpoint1> [endpoint2]
```

## Usage

### Single endpoint (AWS MCP with SigV4)

```bash
mcp-proxy-for-aws-multi https://aws-mcp.us-east-1.api.aws/mcp
```

### Multiple endpoints (AWS MCP + local server)

```bash
mcp-proxy-for-aws-multi https://aws-mcp.us-east-1.api.aws/mcp http://localhost:8000/mcp
```

Tools and resources from both endpoints are merged. Calls are routed to the correct backend automatically.

### MCP Client Configuration

Add to your MCP client config (e.g., Claude Desktop, Kiro CLI):

```json
{
  "mcpServers": {
    "aws-mcp": {
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws-multi@latest",
        "https://aws-mcp.us-east-1.api.aws/mcp",
        "http://localhost:8000/mcp"
      ]
    }
  }
}
```

## Configuration Parameters

| Parameter | Description | Default | Required |
|-----------|-------------|---------|----------|
| `endpoints` | One or more MCP endpoint URLs | N/A | Yes (at least one) |
| `--service` | AWS service name for SigV4 signing | Inferred from endpoint | No |
| `--profile` | AWS profile for credentials | `AWS_PROFILE` env var | No |
| `--region` | AWS region for signing | Inferred from endpoint | No |
| `--metadata` | Metadata key=value pairs to inject | `AWS_REGION` auto-injected | No |
| `--read-only` | Disable tools requiring write permissions | `False` | No |
| `--retries` | Number of retries (0-10) | 0 | No |
| `--log-level` | Logging level | `ERROR` | No |
| `--timeout` | Overall timeout (seconds) | 180 | No |
| `--connect-timeout` | Connection timeout (seconds) | 60 | No |
| `--read-timeout` | Read timeout (seconds) | 120 | No |
| `--write-timeout` | Write timeout (seconds) | 180 | No |
| `--tool-timeout` | Max seconds per tool call | 300 | No |
| `--disable-telemetry` | Disable telemetry | `False` | No |

## How It Works

1. **Endpoint detection** — URLs matching `.api.aws/` are signed with SigV4. Other URLs use plain HTTP.
2. **Provider registration** — each endpoint becomes a FastMCP `ProxyProvider`
3. **Tool merging** — `tools/list` queries all providers in parallel and merges results
4. **Call routing** — `tools/call` is routed to the provider that owns the tool
5. **Same for resources** — `resources/list` and `resources/read` follow the same pattern

## Programmatic Access

The library also provides direct programmatic access for AI agent frameworks:

```python
from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client

mcp_client = aws_iam_streamablehttp_client(
    endpoint="https://aws-mcp.us-east-1.api.aws/mcp",
    aws_region="us-east-1",
    aws_service="execute-api",
)
```

See the [`./examples/mcp-client`](./examples/mcp-client) directory for complete examples with LangChain, LlamaIndex, Strands Agents, and Microsoft Agent Framework.

## Troubleshooting

### Authentication errors
Ensure valid AWS credentials are configured. For long-running sessions, use AWS SSO:
```bash
aws sso login
```
The proxy auto-detects credential expiry and picks up refreshed credentials on the next request.

### Tool call timeouts
Use `--tool-timeout` to set a maximum duration per tool call. Defaults to 300 seconds.

## License

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