How aws/mcp-proxy-for-aws works
Project type and purpose
• This is a Python-based open-source tool and library (“MCP Proxy for AWS”) that provides:
• A standalone CLI/server (the “proxy”) to bridge existing MCP clients (e.g. Claude Desktop, Amazon Q CLI) to IAM-secured MCP servers on AWS
• A programmatic library to plug into Python AI frameworks (LangChain, LlamaIndex, Strands, Microsoft Agent Framework) that handles SigV4 signing and streaming
• It is not a web-app frontend/backend, but rather a protocol-adapter service + client library.
File structure
• Top-level directories:
• mcp_proxy_for_aws/ → core package modules: cli.py, server.py, client.py, middleware, sigv4_helper.py, utils.py, logging_config.py
• examples/mcp-client/ → four framework integration samples (agent-framework, langchain, llamaindex, strands), each with a main.py and environment template
• tests/ (unit & integ) → PyTest tests for every module and end-to-end scenarios
• Dockerfile & docker-healthcheck.sh → containerize the proxy server
• pyproject.toml, .pre-commit, GitHub workflows → build, lint, CI/CD configs
• Key patterns:
• CLI entrypoint → dispatches to server.py
• Proxy server → request pipeline with SigV4 signer middleware and optional tool filtering
• Client library → factory to produce a SigV4-enabled streamable HTTP client
README for additional insights
• Two main usage modes: “MCP Proxy” (CLI/server) vs “Programmatic Access” (library + integration patterns)
• Details on command-line flags, environment variables, example client config JSON
• Integration patterns:
• Pattern 1 (Client Factory)
• Pattern 2 (Direct Session)
Diagramming guidance: representing this project’s architecture
a. Main components
• Local components:
• MCP Client (CLI tool or AI application/framework)
• MCP Proxy for AWS (CLI/server process or Docker container)
• AWS credential provider (environment/CLI profile/IAM role)
• Library components (when used programmatically):
• aws_iam_streamablehttp_client factory
• SigV4 helper module
• Middleware/tool_filter
• External services:
• AWS IAM (for credentials)
• MCP server on AWS (e.g. Amazon Bedrock AgentCore endpoint)
b. Relationships and interactions
• Proxy mode:
MCP Client → (stdio or HTTP) → Proxy Server → SigV4Signer → MCP AWS endpoint → response back
• Library mode:
AI framework → calls aws_iam_streamablehttp_client → returns (read, write) streams → framework wraps in ClientSession → MCP AWS endpoint
c. Architectural patterns/design principles
• Proxy pattern: intercept and transform requests for authentication
• Factory pattern: provide a client factory to frameworks
• Middleware chaining: plug SigV4 signing and tool filtering transparently
• Separation of concerns: CLI orchestration vs signing logic vs transport vs integration
d. Technologies, frameworks, libraries
• Python 3.10+, uv (package manager), asyncio streams
• botocore-style SigV4 signing (sigv4_helper.py)
• Popular AI frameworks (LangChain, LlamaIndex, Strands, Microsoft Agent Framework)
• Docker for containerized deployment