# aws/mcp-proxy-for-aws architecture

> Architecture diagram of the GitHub repository aws/mcp-proxy-for-aws, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws/mcp-proxy-for-aws
- Repository: https://github.com/aws/mcp-proxy-for-aws

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart LR
  subgraph "Proxy Mode"
    direction TB
    CLI["CLI Entrypoint"]:::code
    Server["Proxy Server Core"]:::code
    Middleware["Middleware / Tool-Filtering Pipeline"]:::code
    SigV4["SigV4 Signing Helper"]:::code
    Logging["Logging Configuration Module"]:::code
    Utils["Shared Utility Functions"]:::code
    AWS_Cred["AWS Credential Provider"]:::aws
    CLI --> Server
    Server --> Middleware
    Middleware --> SigV4
    SigV4 --> AWS_Endpoint
    AWS_Cred --> SigV4
  end

  subgraph "Programmatic Library Mode"
    direction TB
    Framework["AI Framework Integration"]:::example
    ClientFactory["Programmatic Client Factory Library"]:::code
    Middleware2["Middleware / Tool-Filtering Pipeline"]:::code
    SigV4_2["SigV4 Signing Helper"]:::code
    Utils2["Shared Utility Functions"]:::code
    AWS_Cred --> ClientFactory
    Framework --> ClientFactory
    ClientFactory --> Middleware2
    Middleware2 --> SigV4_2
    SigV4_2 --> AWS_Endpoint
  end

  AWS_IAM["AWS IAM"]:::aws
  AWS_Endpoint["MCP AWS Endpoint"]:::aws

  AWS_IAM --> AWS_Cred

  subgraph "Example Integrations"
    direction TB
    Agent["Agent Framework Sample"]:::example
    LangChain["LangChain Sample"]:::example
    Llama["LlamaIndex Sample"]:::example
    Strands["Strands Sample"]:::example
    Agent --> ClientFactory
    LangChain --> ClientFactory
    Llama --> ClientFactory
    Strands --> ClientFactory
  end

  subgraph "Deployment & Tests"
    direction TB
    Dockerfile["Dockerized Deployment: Dockerfile"]:::code
    Health["docker-healthcheck.sh"]:::code
    UnitTests["Unit Tests Suite"]:::example
    IntegTests["End-to-End / Integration Tests"]:::example
    PyProject["Project Build & Dependency Config"]:::code
  end

  click CLI "https://github.com/aws/mcp-proxy-for-aws/blob/main/mcp_proxy_for_aws/cli.py"
  click Server "https://github.com/aws/mcp-proxy-for-aws/blob/main/mcp_proxy_for_aws/server.py"
  click SigV4 "https://github.com/aws/mcp-proxy-for-aws/blob/main/mcp_proxy_for_aws/sigv4_helper.py"
  click Middleware "https://github.com/aws/mcp-proxy-for-aws/blob/main/mcp_proxy_for_aws/middleware/tool_filter.py"
  click Logging "https://github.com/aws/mcp-proxy-for-aws/blob/main/mcp_proxy_for_aws/logging_config.py"
  click Utils "https://github.com/aws/mcp-proxy-for-aws/blob/main/mcp_proxy_for_aws/utils.py"
  click ClientFactory "https://github.com/aws/mcp-proxy-for-aws/blob/main/mcp_proxy_for_aws/client.py"
  click Agent "https://github.com/aws/mcp-proxy-for-aws/blob/main/examples/mcp-client/agent-framework/main.py"
  click LangChain "https://github.com/aws/mcp-proxy-for-aws/blob/main/examples/mcp-client/langchain/main.py"
  click Llama "https://github.com/aws/mcp-proxy-for-aws/blob/main/examples/mcp-client/llamaindex/main.py"
  click Strands "https://github.com/aws/mcp-proxy-for-aws/blob/main/examples/mcp-client/strands/main.py"
  click Dockerfile "https://github.com/aws/mcp-proxy-for-aws/tree/main/Dockerfile"
  click Health "https://github.com/aws/mcp-proxy-for-aws/blob/main/docker-healthcheck.sh"
  click UnitTests "https://github.com/aws/mcp-proxy-for-aws/tree/main/tests/unit/"
  click IntegTests "https://github.com/aws/mcp-proxy-for-aws/tree/main/tests/integ/"
  click PyProject "https://github.com/aws/mcp-proxy-for-aws/blob/main/pyproject.toml"

  classDef code fill:#add8e6,stroke:#000,stroke-width:1px;
  classDef aws fill:#ffa500,stroke:#000,stroke-width:1px,shape:cylinder;
  classDef example fill:#90ee90,stroke:#000,stroke-width:1px,shape:parallelogram;
```
