# mikegc-aws/lambda-mcp-server architecture

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

- Interactive diagram: https://gitdiagram.com/mikegc-aws/lambda-mcp-server
- Repository: https://github.com/mikegc-aws/lambda-mcp-server

## Overview

##### Project Type and Purpose
- This is a demonstration full-stack setup comprising:
- A TypeScript HTTP client (Dockerized) that uses the MCP SDK with streamable HTTP
- A Python AWS Lambda-based MCP server behind API Gateway
- Purpose: Show how to build and interact with a stateless, serverless Model Context Protocol (MCP) server (with session state via DynamoDB) and a Bedrock Converse agent client.

##### Break Down the File Structure into Logical Components
- Top-level directories:
- client-http-typescript-docker/… → Dockerized TS client
- server-http-python-lambda/… → AWS SAM serverless stack
- Client sub-components:
- Dockerfile + run-client.sh → container build and run
- src/MCPClient.ts, MCPConverseClient.ts → HTTP client classes
- src/converse/ConverseAgent.ts → Bedrock Converse integration
- src/config/bedrock.ts → Bedrock credentials and endpoints
- Server sub-components:
- template.yaml → AWS SAM definition (API Gateway, Lambdas, DynamoDB)
- authorizer/app.py → custom Lambda authorizer for Bearer token
- server/app.py → entry point registering MCP tools with LambdaMCPServer
- server/lambda_mcp/… → core MCP server library (request parsing, session)
- DynamoDB table (session state) defined via SAM

##### README Insights
- API Gateway with custom Lambda authorizer enforces Bearer token (McpAuthToken)
- LambdaMCPServer provides decorator-based tool registration, session via DynamoDB
- Client uses streamable HTTP over Node.js + Docker, stores token/config locally
- External AWS services: DynamoDB (session), S3 (example tool), Amazon Bedrock Converse API, Amazon Nova Pro

##### Main Components & Relationships
a. Components:
- TypeScript Client (Docker container)
- AWS API Gateway (REST endpoint)
- Lambda Authorizer (custom bearer-token validator)
- Lambda MCP Server (single function with multiple @tool handlers)
- DynamoDB Session Table
- Amazon Bedrock Converse API (external LLM)
- AWS S3 (used by count_s3_buckets tool)
b. Interactions:
1. Client issues HTTP POST to API Gateway’s /mcp endpoint including “Authorization: Bearer <token>”
2. API Gateway invokes Authorizer Lambda → validates token
3. On success, Gateway forwards request to MCP Server Lambda
4. MCP Lambda:
- Unwraps MCP request
- Loads/updates session state in DynamoDB
- Routes to the appropriate @tool handler (e.g., get_weather, count_s3_buckets, say_hello_world)
- If tool calls LLM (Bedrock Converse), it issues a streamable HTTP call, returns stream to client
- If tool calls AWS S3, it invokes AWS SDK
5. MCP Lambda sends SMP-compliant streamed response back through API Gateway → client
c. Architectural Patterns:
- Serverless (Function-as-a-Service) behind API Gateway
- Plugin/decorator pattern for tool registration
- Stateless Lambdas with external state in DynamoDB
- Streamable HTTP for live responses
d. Key Technologies:
- Python 3.9+, AWS SAM, boto3, DynamoDB
- Node.js, TypeScript, Docker, ModelContextProtocol SDK
- Amazon Bedrock Converse API & Nova Pro
- AWS S3, AWS API Gateway, Lambda authorizers

##### Detail Is Key
- Break out:
- Authorizer vs. main Lambda
- Tool invocation vs. session management vs. external API calls
- Environment variables (e.g., MCP_SESSION_TABLE, MCP_AUTH_TOKEN)
- Docker build/run for client

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "TypeScript Client (Dockerized)" 
        direction TB
        ClientIndex["index.ts"]:::client
        MCPClient["MCPClient.ts"]:::client
        MCPConverseClient["MCPConverseClient.ts"]:::client
        ConverseAgent["ConverseAgent.ts"]:::client
        ConverseTools["ConverseTools.ts"]:::client
        ConverseTypes["types.ts"]:::client
        BedrockConfig["bedrock.ts"]:::client
        DockerfileClient["Dockerfile"]:::client
        RunScript["run-client.sh"]:::client
    end

    %% API Layer
    subgraph "API Layer" 
        direction TB
        APIGateway["API Gateway /mcp"]:::api
        Authorizer["Lambda Authorizer"]:::api
    end

    %% Server Layer
    subgraph "MCP Server (Python Lambda)" 
        direction TB
        Template["template.yaml"]:::infra
        LambdaEntry["server/app.py"]:::server
        subgraph "Core MCP Library" 
            direction TB
            LambdaMCP["lambda_mcp.py"]:::server
            Session["session.py"]:::server
            Types["types.py"]:::server
        end
        Requirements["requirements.txt"]:::infra
    end

    %% Data Stores
    DynamoDB["DynamoDB Session Table"]:::db

    %% External Services
    Bedrock["Amazon Bedrock Converse API"]:::external
    S3["AWS S3"]:::external

    %% Connections
    ClientIndex -->|"build & run"| DockerfileClient
    DockerfileClient --> RunScript
    RunScript -->|"HTTP POST /mcp"| APIGateway
    APIGateway -->|"Authorizes"| Authorizer
    Authorizer -->|"Valid"| APIGateway
    APIGateway -->|"Invoke MCP Lambda"| LambdaEntry
    LambdaEntry -->|"uses core lib"| LambdaMCP
    LambdaEntry --> LambdaMCP
    LambdaMCP --> Session
    LambdaMCP --> Types
    LambdaMCP -->|"read/write"| DynamoDB
    LambdaMCP -->|"call tool"| Bedrock
    LambdaMCP -->|"call tool"| S3
    LambdaEntry -->|"returns stream"| APIGateway
    APIGateway -->|"streamable HTTP"| RunScript

    %% Click Events
    click ClientIndex "https://github.com/mikegc-aws/lambda-mcp-server/blob/main/client-http-typescript-docker/client/src/index.ts"
    click MCPClient "https://github.com/mikegc-aws/lambda-mcp-server/blob/main/client-http-typescript-docker/client/src/MCPClient.ts"
    click MCPConverseClient "https://github.com/mikegc-aws/lambda-mcp-server/blob/main/client-http-typescript-docker/client/src/MCPConverseClient.ts"
    click ConverseAgent "https://github.com/mikegc-aws/lambda-mcp-server/blob/main/client-http-typescript-docker/client/src/converse/ConverseAgent.ts"
    click ConverseTools "https://github.com/mikegc-aws/lambda-mcp-server/blob/main/client-http-typescript-docker/client/src/converse/ConverseTools.ts"
    click ConverseTypes "https://github.com/mikegc-aws/lambda-mcp-server/blob/main/client-http-typescript-docker/client/src/converse/types.ts"
    click BedrockConfig "https://github.com/mikegc-aws/lambda-mcp-server/blob/main/client-http-typescript-docker/client/src/config/bedrock.ts"
    click DockerfileClient "https://github.com/mikegc-aws/lambda-mcp-server/tree/main/client-http-typescript-docker/client/Dockerfile"
    click RunScript "https://github.com/mikegc-aws/lambda-mcp-server/blob/main/client-http-typescript-docker/run-client.sh"
    click Template "https://github.com/mikegc-aws/lambda-mcp-server/blob/main/server-http-python-lambda/template.yaml"
    click Authorizer "https://github.com/mikegc-aws/lambda-mcp-server/blob/main/server-http-python-lambda/authorizer/app.py"
    click Requirements "https://github.com/mikegc-aws/lambda-mcp-server/blob/main/server-http-python-lambda/authorizer/requirements.txt"
    click LambdaEntry "https://github.com/mikegc-aws/lambda-mcp-server/blob/main/server-http-python-lambda/server/app.py"
    click LambdaMCP "https://github.com/mikegc-aws/lambda-mcp-server/blob/main/server-http-python-lambda/server/lambda_mcp/lambda_mcp.py"
    click Session "https://github.com/mikegc-aws/lambda-mcp-server/blob/main/server-http-python-lambda/server/lambda_mcp/session.py"
    click Types "https://github.com/mikegc-aws/lambda-mcp-server/blob/main/server-http-python-lambda/server/lambda_mcp/types.py"
    click Requirements "https://github.com/mikegc-aws/lambda-mcp-server/blob/main/server-http-python-lambda/server/requirements.txt"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef api fill:#E6FFED,stroke:#22863A,color:#22863A;
    classDef server fill:#FFF5D1,stroke:#D93F0B,color:#D93F0B;
    classDef infra fill:#F0F0F0,stroke:#666666,color:#333333;
    classDef db fill:#FFE4E1,stroke:#B31D1D,color:#B31D1D;
    classDef external fill:#F0FFF0,stroke:#008080,color:#008080
```
