Skip to content

Commit 4d8148d

Browse files
acmlauacmlau
authored
Update readme (#35)
* Add region to CLI arguments * Updating default region to us-east-1 * Add region utils * Remove auth parameter * Undo removal of auth parameter * Make region non optional parameter * Resolving merge conflict * Fix formatting * Updating README.md * Fixing formatting * Updating README.md
1 parent be7bb66 commit 4d8148d

File tree

1 file changed

+95
-73
lines changed

1 file changed

+95
-73
lines changed

‎README.md‎

Lines changed: 95 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,10 @@
1-
# AWS aws-mcp-proxy MCP Server
1+
# README: AWS MCP Proxy
22

3-
AWS MCP Proxy Server
3+
AWS MCP Proxy Server
44

55
## Overview
66

7-
The AWS MCP Proxy serves as a lightweight, client-side bridge between MCP clients (AI assistants and developer tools) and backend AWS services.
8-
9-
- **MCP Mode (Default)**: Direct connection to a single MCP backend server using JSON-RPC protocol
7+
The AWS MCP Proxy serves as a lightweight, client-side bridge between MCP clients (AI assistants and developer tools) and backend AWS MCP servers.
108

119
The proxy handles SigV4 authentication using local AWS credentials and provides dynamic tool discovery, making it ideal for developers who want direct service access without complex gateway setups.
1210

@@ -15,108 +13,132 @@ The proxy handles SigV4 authentication using local AWS credentials and provides
1513
* [Install Python 3.10+](https://www.python.org/downloads/release/python-3100/)
1614
* [Install the `uv` package manager](https://docs.astral.sh/uv/getting-started/installation/)
1715
* [Install and configure the AWS CLI with credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)
16+
* (Optional, for docker users) [Install Docker Desktop](https://www.docker.com/products/docker-desktop)
17+
18+
## Installation
19+
20+
### Using PyPi
1821

19-
## Getting Started
22+
*Note: will work after publishing to PyPi*
23+
24+
```
25+
# Run the server
26+
uvx aws-mcp-proxy <SigV4 MCP endpoint URL>
27+
```
2028

21-
### Quick start
29+
### Using Local Repository
2230

23-
```bash
24-
uv run aws_mcp_proxy/server.py <a sigv4 mcp>
31+
```
32+
git clone https://github.com/aws/aws-mcp-proxy.git
33+
cd aws-mcp-proxy
34+
uv run aws_mcp_proxy/server.py <SigV4 MCP endpoint URL>
2535
```
2636

27-
#### Details
37+
### Using Docker
2838

29-
MCP mode provides a streamlined connection to a single backend MCP server.
39+
```
40+
# Build the Docker image
41+
docker build -t aws-mcp-proxy .
42+
```
3043

31-
#### 1. Configure MCP Client
44+
## Configuration Parameters
3245

33-
Add this to your MCP client configuration, replacing env variables to match the AWS credentials and region you want to use:
46+
|Parameter |Description |Default |Required |
47+
|--- |--- |--- |--- |
48+
|`endpoint` |MCP endpoint URL (e.g., `https://your-service.us-east-1.amazonaws.com/mcp`) |N/A |Yes |
49+
|--- |--- |--- |--- |
50+
|`--service` |AWS service name for SigV4 signing |Inferred from endpoint if not provided |No |
51+
|`--profile` |AWS profile for AWS credentials to use |Uses `AWS_PROFILE` environment variable if not set|No |
52+
|`--region` |AWS region to use |Uses `AWS_REGION` environment variable if not set, defaults to `us-east-1` |No |
53+
|`--read-only` |Disable tools which may require write permissions (tools which DO NOT require write permissions are annotated with [`readOnlyHint=true`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint))|`False` |No |
54+
| `--retries` |Configures number of retries done when calling upstream services, setting this to 0 disables retries. | 0 |No |
55+
|`--log-level` |Set the logging level (`DEBUG/INFO/WARNING/ERROR/CRITICAL`) |`INFO` |No |
3456

35-
Optional arguments you can add:
36-
- `--service`: AWS service name for SigV4 signing (inferred from endpoint if not provided)
37-
- `--profile`: AWS profile to use (uses AWS_PROFILE environment variable if not provided)
38-
- `--read-only`: Disable tools which require write permissions. (tools which DO NOT require write permissions are annotated with [`readOnlyHint=true`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint))
39-
- `--retries`: Configures number of retries done when calling upstream services, setting this to 0 disables retries.
57+
## Optional Environment Variables
4058

41-
NOTE: `remote-server-url` should be your remote mcp server's URL (including the `/mcp` part). `service-code` should be the service code for the MCP to be connected.
59+
Set the environment variables for the AWS MCP Proxy:
4260

43-
Example with all options
44-
```json
61+
```
62+
# Credentials through profile
63+
export AWS_PROFILE=<aws_profile>
64+
65+
# Credentials through parameters
66+
export AWS_ACCESS_KEY_ID=<access_key_id>
67+
export AWS_SECRET_ACCESS_KEY=<secret_access_key>
68+
export AWS_SESSION_TOKEN=<session_token>
69+
70+
# AWS Region
71+
export AWS_REGION=<aws_region>
72+
```
73+
74+
## Setup Examples
75+
76+
Add the following configuration to your MCP client config file (e.g., for Amazon Q Developer CLI, edit `~/.aws/amazonq/mcp.json`):
77+
**Note** Add your own endpoint by replacing `<SigV4 MCP endpoint URL>`
78+
79+
### Running from local - using uv
80+
81+
```
4582
{
4683
"mcpServers": {
47-
"aws.aws-mcp-proxy": {
84+
"aws-mcp-proxy": {
4885
"disabled": false,
4986
"type": "stdio",
5087
"command": "uv",
5188
"args": [
5289
"--directory",
5390
"/path/to/aws_mcp_proxy",
5491
"run",
55-
"aws_mcp_proxy/server.py",
56-
"<remote-server-url>",
92+
"server.py",
93+
"<SigV4 MCP endpoint URL>",
5794
"--service",
58-
"<service-code>",
95+
"<your service code>",
5996
"--profile",
6097
"default",
61-
"--read-only"
98+
"--region",
99+
"us-east-1",
100+
"--read-only",
101+
"--log-level",
102+
"INFO",
62103
]
63104
}
64105
}
65106
}
66107
```
67108

68-
#### 2. Backend Server Configuration
69-
70-
In MCP mode, the backend server is configured directly through command-line arguments:
109+
### Using Docker
71110

72-
* `endpoint`: The MCP endpoint URL (required, first positional argument)
73-
* `--service`: AWS service name for SigV4 signing (optional, inferred from endpoint if not provided)
74-
* `--profile`: AWS profile to use (optional, uses AWS_PROFILE environment variable if not provided)
75-
76-
The proxy will automatically connect to the specified backend MCP server and discover available tools.
77-
78-
### Tool Discovery and Updates
79-
80-
The proxy automatically manages tool discovery and updates:
81-
82-
1. **MCP Mode**: Connects directly to the backend MCP server and discovers available tools
83-
3. **Dynamic Updates**: Automatically checks for tool updates when tools are called - Currently not implemented for MCP (default) mode.
84-
4. **Validation**: Ensures tool parameters match the current specification
85-
86-
**Note**: Currently, a limited number of MCP clients (such as Amazon Q CLI) support automatic refresh of tool lists. In most cases, clients do not handle the `notifications/tools/list_changed` message by making a new `tools/list` call to refresh the tool list. The server needs to be refreshed manually in order for them to pick up changes.
87-
88-
## TODO (REMOVE AFTER COMPLETING)
89-
90-
* [ ] Add your own tool(s) following the [DESIGN_GUIDELINES.md](https://github.com/aws/mcp/blob/main/DESIGN_GUIDELINES.md)
91-
* [ ] Keep test coverage at or above the `main` branch - NOTE: GitHub Actions run this command for CodeCov metrics `uv run --frozen pytest --cov --cov-branch --cov-report=term-missing`
92-
* [ ] Document the MCP Server in this "README.md"
93-
* [ ] Add a section for this aws-mcp-proxy MCP Server at the top level of this repository "../../README.md"
94-
* [ ] Create the "../../doc/servers/aws-mcp-proxy.md" file with these contents:
95-
96-
```markdown
97-
---
98-
title: aws-mcp-proxy MCP Server
99-
---
100-
101-
{% include "../../src/aws-mcp-proxy/README.md" %}
102-
```
103-
104-
* [ ] Reference within the "../../doc/index.md" like this:
111+
```
112+
{
113+
"mcpServers": {
114+
"aws-mcp-proxy": {
115+
"command": "docker",
116+
"args": [
117+
"run",
118+
"--rm",
119+
"--volume",
120+
"/full/path/to/.aws:/app/.aws:ro",
121+
"aws-mcp-proxy",
122+
"<SigV4 MCP endpoint URL>"
123+
],
124+
"env": {}
125+
}
126+
}
127+
}
128+
```
105129

106-
```markdown
107-
### aws-mcp-proxy MCP Server
130+
## Development & Contributing
108131

109-
AWS MCP Proxy Server
132+
For development setup, testing, and contribution guidelines, see:
110133

111-
**Features:**
134+
* [DEVELOPMENT.md](DEVELOPMENT.md) - Development environment setup and testing
135+
* [CONTRIBUTING.md](CONTRIBUTING.md) - How to contribute to this project
112136

113-
- Feature one
114-
- Feature two
115-
- ...
137+
## License
116138

117-
Instructions for using this aws-mcp-proxy MCP server. This can be used by clients to improve the LLM's understanding of available tools, resources, etc. It can be thought of like a 'hint' to the model. For example, this information MAY be added to the system prompt. Important to be clear, direct, and detailed.
139+
Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
140+
Licensed under the Apache License, Version 2.0 (the "License").
118141

119-
[Learn more about the aws-mcp-proxy MCP Server](servers/aws-mcp-proxy.md)
120-
```
142+
## Disclaimer
121143

122-
* [ ] Submit a PR and pass all the checks
144+
This aws-mcp-proxy package is provided "as is" without warranty of any kind, express or implied, and is intended for development, testing, and evaluation purposes only. We do not provide any guarantee on the quality, performance, or reliability of this package. LLMs are non-deterministic and they make mistakes, we advise you to always thoroughly test and follow the best practices of your organization before using these tools on customer facing accounts. Users of this package are solely responsible for implementing proper security controls and MUST use AWS Identity and Access Management (IAM) to manage access to AWS resources. You are responsible for configuring appropriate IAM policies, roles, and permissions, and any security vulnerabilities resulting from improper IAM configuration are your sole responsibility. By using this package, you acknowledge that you have read and understood this disclaimer and agree to use the package at your own risk.

0 commit comments

Comments
 (0)