You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The MCP Proxy for AWS serves as a lightweight, client-side bridge between MCP clients (AI assistants and developer tools) and backend AWS MCP servers.
5
+
The **MCP Proxy for AWS** package provides two ways to connect AI applications to MCP servers on AWS:
6
6
7
-
The proxy handles [SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) authentication using local AWS credentials and provides dynamic tool discovery, making it ideal for developers who want access to AWS Hosted SigV4 secured MCP Servers without complex gateway setups.
7
+
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](#mcp-proxy))
8
+
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))
9
+
10
+
11
+
### When Do You Need This Package?
12
+
13
+
- You want to connect to **MCP servers on AWS** (e.g., using Amazon Bedrock AgentCore) that use AWS IAM authentication (SigV4) instead of OAuth
14
+
- You're using MCP clients (like Claude Desktop, Amazon Q Developer CLI) that don't natively support AWS IAM authentication
15
+
- You're building AI agents with popular frameworks like LangChain, Strands Agents, LlamaIndex, etc., that need to connect to MCP servers on AWS
16
+
- You want to avoid building custom SigV4 request signing logic yourself
17
+
18
+
### How This Package Helps
19
+
20
+
**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.
21
+
22
+
**The Solution:** This package bridges that gap by:
23
+
-**Handling SigV4 authentication automatically** - Uses your local AWS credentials (from AWS CLI, environment variables, or IAM roles) to sign all MCP requests using [SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)
24
+
-**Providing seamless integration** - Works with existing MCP clients and frameworks
25
+
-**Eliminating custom code** - No need to build your own MCP client with SigV4 signing logic
26
+
27
+
## Which Feature Should I Use?
28
+
29
+
**Use as a proxy if you want to:**
30
+
- Connect MCP clients like Claude Desktop or Amazon Q Developer CLI to MCP servers on AWS with IAM credentials
31
+
- Add MCP servers on AWS to your AI assistant's configuration
32
+
- Use a command-line tool that runs as a bridge between your MCP client and AWS
33
+
34
+
**Use as a library if you want to:**
35
+
- Build AI agents programmatically using popular frameworks like LangChain, Strands Agents, or LlamaIndex
36
+
- Integrate AWS IAM-secured MCP servers directly into your Python applications
37
+
- Have fine-grained control over the MCP session lifecycle in your code
*[Install the `uv` package manager](https://docs.astral.sh/uv/getting-started/installation/)
13
-
*[Install and configure the AWS CLI with credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)
43
+
*AWS credentials configured (via [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html), environment variables, or IAM roles)
14
44
* (Optional, for docker users) [Install Docker Desktop](https://www.docker.com/products/docker-desktop)
15
45
16
-
## Installation
46
+
---
17
47
18
-
### Using PyPi
48
+
##MCP Proxy
19
49
50
+
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.
Add the following configuration to your MCP client config file (e.g., for Amazon Q Developer CLI, edit `~/.aws/amazonq/mcp.json`):
79
113
**Note** Add your own endpoint by replacing `<SigV4 MCP endpoint URL>`
80
114
81
-
### Running from local - using uv
115
+
####Running from local - using uv
82
116
83
-
```
117
+
```json
84
118
{
85
119
"mcpServers": {
86
120
"<mcp server name>": {
@@ -108,9 +142,9 @@ Add the following configuration to your MCP client config file (e.g., for Amazon
108
142
}
109
143
```
110
144
111
-
### Using Docker
145
+
####Using Docker
112
146
113
-
```
147
+
```json
114
148
{
115
149
"mcpServers": {
116
150
"<mcp server name>": {
@@ -129,6 +163,121 @@ Add the following configuration to your MCP client config file (e.g., for Amazon
129
163
}
130
164
```
131
165
166
+
---
167
+
168
+
## Programmatic Access
169
+
170
+
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.
171
+
172
+
### Integration Patterns
173
+
174
+
The library supports two integration patterns depending on your framework:
175
+
176
+
#### Pattern 1: Client Factory Integration
177
+
178
+
**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.
179
+
180
+
**Example - Strands Agents:**
181
+
```python
182
+
from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client
**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`.
215
+
216
+
**Example - LangChain:**
217
+
```python
218
+
from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client
219
+
220
+
mcp_client = aws_iam_streamablehttp_client(
221
+
endpoint=mcp_url, # The URL of the MCP server
222
+
aws_region=region, # The region of the MCP server
223
+
aws_service=service # The underlying AWS service, e.g. "bedrock-agentcore"
224
+
)
225
+
226
+
asyncwith mcp_client as (read, write, session_id_callback):
This example demonstrates how to use `aws_iam_streamablehttp_client` from `mcp-proxy-for-aws` to connect a [Microsoft Agent Framework](https://learn.microsoft.com/en-us/agent-framework/) agent to an MCP server using AWS IAM authentication.
4
+
5
+
**Note:** Microsoft Agent Framework accepts a factory function that returns an MCP client. The `aws_iam_streamablehttp_client` is passed as a factory to the framework's `MCPStreamableHTTPTool`, which handles the connection lifecycle internally.
6
+
7
+
## Prerequisites
8
+
9
+
-[Python 3.10+](https://www.python.org/downloads) and [uv](https://docs.astral.sh/uv/getting-started/installation/) installed
10
+
- AWS credentials configured (via [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html), environment variables, or IAM roles)
11
+
- An [OpenAI API key](https://platform.openai.com/api-keys) for the language model
12
+
13
+
## Setup
14
+
15
+
Create a `.env` file or set the following environment variables:
- Verify AWS credentials are configured ([AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html), environment variables, or IAM roles)
68
+
- Test with `aws sts get-caller-identity`
69
+
70
+
#### Missing environment variables
71
+
72
+
- Ensure all required variables are set: `MCP_SERVER_URL`, `MCP_SERVER_REGION`, `MCP_SERVER_AWS_SERVICE`, and `OPENAI_API_KEY`
73
+
- Check your `.env` file or environment variable configuration
74
+
75
+
#### Connection errors
76
+
77
+
- Verify your MCP server details are correct
78
+
- Ensure the MCP server is running and accessible
79
+
- Verify your AWS credentials have the necessary permissions to access the MCP server
0 commit comments