Skip to content

Commit 4f66e6d

Browse files
DennisTraubDennisTraub
committed
Update README
1 parent 1bd7a5a commit 4f66e6d

File tree

1 file changed

+171
-21
lines changed

1 file changed

+171
-21
lines changed

‎README.md‎

Lines changed: 171 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -2,43 +2,77 @@
22

33
## Overview
44

5-
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:
66

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. **MCP Proxy** - 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. **MCP Client Library** - A Python library to programmatically connect popular AI agent frameworks (LangChain, LlamaIndex, Strands Agents, etc.) to MCP servers on AWS. (See [MCP Client Library](#mcp-client-library))
9+
10+
### When Do You Need This Package?
11+
12+
- You want to connect to **MCP servers on AWS** (e.g., using Amazon Bedrock AgentCore) that use AWS IAM authentication (SigV4) instead of OAuth
13+
- You're using MCP clients (like Claude Desktop, Amazon Q Developer CLI) that don't natively support AWS IAM authentication
14+
- You're building AI agents with popular frameworks like LangChain, Strands Agents, LlamaIndex, etc., that need to connect to MCP servers on AWS
15+
- You want to avoid building custom SigV4 request signing logic yourself
16+
17+
### How This Package Helps
18+
19+
**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.
20+
21+
**The Solution:** This package bridges that gap by:
22+
- **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)
23+
- **Providing seamless integration** - Works with existing MCP clients and frameworks
24+
- **Eliminating custom code** - No need to build your own MCP client with SigV4 signing logic
25+
26+
## Which Feature Should I Use?
27+
28+
**Use the MCP Proxy if you want to:**
29+
- Connect MCP clients like Claude Desktop or Amazon Q Developer CLI to MCP servers on AWS with IAM credentials
30+
- Add MCP servers on AWS to your AI assistant's configuration
31+
- Use a command-line tool that runs as a bridge between your MCP client and AWS
32+
33+
**Use the MCP Client Library if you want to:**
34+
- Build AI agents programmatically using popular frameworks like LangChain, Strands Agents, or LlamaIndex
35+
- Integrate AWS IAM-secured MCP servers directly into your Python applications
36+
- Have fine-grained control over the MCP session lifecycle in your code
837

938
## Prerequisites
1039

1140
* [Install Python 3.10+](https://www.python.org/downloads/release/python-3100/)
1241
* [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)
42+
* AWS credentials configured (via [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html), environment variables, or IAM roles)
1443
* (Optional, for docker users) [Install Docker Desktop](https://www.docker.com/products/docker-desktop)
1544

16-
## Installation
45+
---
1746

18-
### Using PyPi
47+
## MCP Proxy
1948

49+
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.
2050

21-
```
51+
### Installation
52+
53+
#### Using PyPi
54+
55+
```bash
2256
# Run the server
2357
uvx mcp-proxy-for-aws@latest <SigV4 MCP endpoint URL>
2458
```
2559

26-
### Using Local Repository
60+
#### Using a local repository
2761

28-
```
62+
```bash
2963
git clone https://github.com/aws/mcp-proxy-for-aws.git
3064
cd mcp-proxy-for-aws
3165
uv run mcp_proxy_for_aws/server.py <SigV4 MCP endpoint URL>
3266
```
3367

34-
### Using Docker
68+
#### Using Docker
3569

36-
```
70+
```bash
3771
# Build the Docker image
3872
docker build -t mcp-proxy-for-aws .
3973
```
4074

41-
## Configuration Parameters
75+
### Configuration Parameters
4276

4377
| Parameter | Description | Default |Required |
4478
|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|--- |
@@ -55,12 +89,11 @@ docker build -t mcp-proxy-for-aws .
5589
| `--read-timeout` | Set desired read timeout in seconds | 120 |No |
5690
| `--write-timeout` | Set desired write timeout in seconds | 180 |No |
5791

58-
59-
## Optional Environment Variables
92+
### Optional Environment Variables
6093

6194
Set the environment variables for the MCP Proxy for AWS:
6295

63-
```
96+
```bash
6497
# Credentials through profile
6598
export AWS_PROFILE=<aws_profile>
6699

@@ -73,14 +106,14 @@ export AWS_SESSION_TOKEN=<session_token>
73106
export AWS_REGION=<aws_region>
74107
```
75108

76-
## Setup Examples
109+
### Setup Examples
77110

78111
Add the following configuration to your MCP client config file (e.g., for Amazon Q Developer CLI, edit `~/.aws/amazonq/mcp.json`):
79112
**Note** Add your own endpoint by replacing `<SigV4 MCP endpoint URL>`
80113

81-
### Running from local - using uv
114+
#### Running from local - using uv
82115

83-
```
116+
```json
84117
{
85118
"mcpServers": {
86119
"<mcp server name>": {
@@ -108,9 +141,9 @@ Add the following configuration to your MCP client config file (e.g., for Amazon
108141
}
109142
```
110143

111-
### Using Docker
144+
#### Using Docker
112145

113-
```
146+
```json
114147
{
115148
"mcpServers": {
116149
"<mcp server name>": {
@@ -129,6 +162,123 @@ Add the following configuration to your MCP client config file (e.g., for Amazon
129162
}
130163
```
131164

165+
For additional proxy examples, see [`./examples/mcp-proxy`](./examples/mcp-proxy).
166+
167+
---
168+
169+
## MCP Client Library
170+
171+
The MCP Client Library 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.
172+
173+
### Integration Patterns
174+
175+
The library supports two integration patterns depending on your framework:
176+
177+
#### Pattern 1: Framework-Native MCP Integration
178+
179+
**Use with:** Frameworks that provide their own MCP client implementations accepting connection factories, e.g. Strands Agents SDK, Microsoft Agent Framework. The AWS IAM MCP Client provides the authenticated transport layer.
180+
181+
**Example - Strands Agents SDK:**
182+
```python
183+
from mcp_proxy_for_aws.client import aws_iam_mcp_client
184+
185+
iam_client_factory = lambda: aws_iam_mcp_client(
186+
endpoint=mcp_url, # The URL of the MCP server
187+
aws_region=region, # The region of the MCP server
188+
aws_service=service # The underlying AWS service, e.g. "bedrock-agentcore"
189+
)
190+
191+
with MCPClient(iam_client_factory) as mcp_client:
192+
mcp_tools = mcp_client.list_tools_sync()
193+
agent = Agent(tools=mcp_tools, ...)
194+
```
195+
196+
**Example - Microsoft Agent Framework:**
197+
```python
198+
from mcp_proxy_for_aws.client import aws_iam_mcp_client
199+
200+
iam_client_factory = lambda: aws_iam_mcp_client(
201+
endpoint=mcp_url, # The URL of the MCP server
202+
aws_region=region, # The region of the MCP server
203+
aws_service=service # The underlying AWS service, e.g. "bedrock-agentcore"
204+
)
205+
206+
mcp_tools = MCPStreamableHTTPTool(name="MCP Tools", url=mcp_url)
207+
mcp_tools.get_mcp_client = iam_client_factory
208+
209+
async with mcp_client:
210+
agent = ChatAgent(tools=mcp_tools, ...)
211+
```
212+
213+
#### Pattern 2: Direct MCP Session Integration
214+
215+
**Use with:** Frameworks that require direct access to MCP sessions, e.g. LangChain, LlamaIndex. The AWS IAM MCP Client provides the authenticated transport, and you can manually manage the MCP session lifecycle.
216+
217+
**Example - LangChain:**
218+
```python
219+
from mcp_proxy_for_aws.client import aws_iam_mcp_client
220+
221+
iam_client = aws_iam_mcp_client(
222+
endpoint=mcp_url, # The URL of the MCP server
223+
aws_region=region, # The region of the MCP server
224+
aws_service=service # The underlying AWS service, e.g. "bedrock-agentcore"
225+
)
226+
227+
async with iam_client as (read, write, session_id_callback):
228+
async with ClientSession(read, write) as session:
229+
mcp_tools = await load_mcp_tools(session)
230+
agent = create_langchain_agent(tools=mcp_tools, ...)
231+
```
232+
233+
**Example - LlamaIndex:**
234+
```python
235+
from mcp_proxy_for_aws.client import aws_iam_mcp_client
236+
237+
iam_client = aws_iam_mcp_client(
238+
endpoint=mcp_url, # The URL of the MCP server
239+
aws_region=region, # The region of the MCP server
240+
aws_service=service # The underlying AWS service, e.g. "bedrock-agentcore"
241+
)
242+
243+
async with iam_client as (read, write, session_id_callback):
244+
async with ClientSession(read, write) as session:
245+
tools = await McpToolSpec(client=session).to_tool_list_async()
246+
agent = ReActAgent(llm=model, tools=tools)
247+
```
248+
249+
### Running Examples
250+
251+
Explore complete working examples for different frameworks in the [`./examples/mcp-client`](./examples/mcp-client) directory:
252+
253+
**Available examples:**
254+
- **[Strands Agents SDK](./examples/mcp-client/strands/)**
255+
- **[Microsoft Agent Framework](./examples/mcp-client/agent-framework/)**
256+
- **[LangChain](./examples/mcp-client/langchain/)**
257+
- **[LlamaIndex](./examples/mcp-client/llamaindex/)**
258+
259+
Run examples individually:
260+
```bash
261+
cd examples/mcp-client/[framework] # e.g. examples/mcp-client/strands
262+
uv run main.py
263+
```
264+
265+
### Installation
266+
267+
The client library is included when you install the package:
268+
269+
```bash
270+
pip install mcp-proxy-for-aws
271+
```
272+
273+
For development:
274+
```bash
275+
git clone https://github.com/aws/mcp-proxy-for-aws.git
276+
cd mcp-proxy-for-aws
277+
uv sync
278+
```
279+
280+
---
281+
132282
## Development & Contributing
133283

134284
For development setup, testing, and contribution guidelines, see:
@@ -138,8 +288,8 @@ For development setup, testing, and contribution guidelines, see:
138288

139289
Resources to understand SigV4:
140290

141-
- <https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html>
142-
- SigV4: <https://github.com/boto/botocore/blob/develop/botocore/signers.py>
291+
- SigV4 User Guide: <https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html>
292+
- SigV4 Signers: <https://github.com/boto/botocore/blob/develop/botocore/signers.py>
143293
- SigV4a: <https://github.com/aws-samples/sigv4a-signing-examples/blob/main/python/sigv4a_sign.py>
144294

145295
## License

0 commit comments

Comments
 (0)