# aws-samples/sample-serverless-mcp-servers architecture

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

- Interactive diagram: https://gitdiagram.com/aws-samples/sample-serverless-mcp-servers
- Repository: https://github.com/aws-samples/sample-serverless-mcp-servers

## Overview

##### Project type and purpose
- This is an open-source collection of sample MCP (Model Context Protocol) Server implementations.
- It demonstrates four “production-style” deployment patterns:
- Stateless on Lambda (Node.js + Terraform)
- Stateless on Lambda (Python + SAM)
- Stateless on ECS (Node.js + Terraform)
- Stateful on ECS (Node.js + Terraform)
- Plus a “lambda-ops-mcp-server” PoC for local MCP server operations.

##### File structure
- Top-level directories each correspond to one sample deployment.
- Each sample folder has two halves:
a. src/mcpserver (+ optional authorizer) and src/mcpclient
b. IaC/config (Terraform .tf files or SAM template) and build scripts (publish-to-ecr.sh, makefile)
- The lambda-ops-mcp-server folder is a standalone Node.js project with tools/ and utils/ subfolders.

##### Extract architecture from the README
- Key technologies: AWS Lambda, API Gateway, AWS ECS (Fargate/EC2), ALB, Terraform, AWS SAM, Node.js, Python.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Stateless Lambda (Node.js)
    subgraph "Stateless Lambda (Node.js)"
      direction TB
      SLN_Client["MCP Client"]:::client
      SLN_API["API Gateway (GET/POST)"]:::network
      SLN_Authorizer["Lambda Authorizer"]:::compute
      SLN_Transport["transport.js"]:::compute
      SLN_Lambda["Lambda: mcp-server.js"]:::compute
      SLN_IaC["Terraform"]:::infra

      SLN_Client -->|"GET/POST"| SLN_API
      SLN_API -->|"authorize"| SLN_Authorizer
      SLN_API -->|"invoke"| SLN_Lambda
      SLN_Lambda -->|"SSE/HTTP"| SLN_Client
      SLN_Transport --> SLN_Lambda
    end

    %% Stateless Lambda (Python)
    subgraph "Stateless Lambda (Python)"
      direction TB
      SLP_Client["MCP Client"]:::client
      SLP_API["API Gateway (GET/POST)"]:::network
      SLP_Transport["server.py"]:::compute
      SLP_Lambda["Lambda: echo.py"]:::compute
      SLP_IaC["SAM"]:::infra

      SLP_Client -->|"GET/POST"| SLP_API
      SLP_API -->|"invoke"| SLP_Transport
      SLP_Transport --> SLP_Lambda
      SLP_Lambda -->|"SSE/HTTP"| SLP_Client
    end

    %% Stateless ECS (Node.js)
    subgraph "Stateless ECS (Node.js)"
      direction TB
      SEC_Client["MCP Client"]:::client
      SEC_ALB["ALB (GET/POST)"]:::network
      SEC_Transport["transport.js"]:::compute
      SEC_Container["ECS Task: mcp-server.js"]:::compute
      SEC_IaC["Terraform"]:::infra

      SEC_Client -->|"GET/POST"| SEC_ALB
      SEC_ALB -->|"route"| SEC_Container
      SEC_Container -->|"SSE/HTTP"| SEC_Client
      SEC_Transport --> SEC_Container
    end

    %% Stateful ECS (Node.js)
    subgraph "Stateful ECS (Node.js)"
      direction TB
      STC_Client["MCP Client"]:::client
      STC_ALB["ALB (GET/POST)"]:::network
      STC_Transport["transport.js"]:::compute
      STC_Container["ECS Task: mcp-server.js\n(in-memory sessions)"]:::compute
      STC_IaC["Terraform"]:::infra
      STC_Sticky["Cookie Stickiness"]:::network

      STC_Client -->|"GET/POST"| STC_ALB
      STC_ALB -->|"sticky route"| STC_Container
      STC_Container -->|"SSE/HTTP"| STC_Client
      STC_Transport --> STC_Container
    end

    %% Lambda Ops PoC
    subgraph "lambda-ops-mcp-server PoC (Local)"
      direction TB
      LOC_Tools["Tools/*.js"]:::compute
      LOC_Utils["Utils/*.js"]:::compute
      LOC_Server["Core Server\nindex.js / mcp-server.js"]:::compute
      LOC_AWS["AWS Lambda\nvia AWS SDK"]:::network

      LOC_Tools --> LOC_Server
      LOC_Utils --> LOC_Server
      LOC_Server -->|"list/invoke/update"| LOC_AWS
    end

    %% Click Events
    click SLN_Client "https://github.com/aws-samples/sample-serverless-mcp-servers/blob/main/stateless-mcp-on-lambda-nodejs/src/mcpclient/index.js"
    click SLN_API "https://github.com/aws-samples/sample-serverless-mcp-servers/blob/main/stateless-mcp-on-lambda-nodejs/terraform/apigateway.tf"
    click SLN_Authorizer "https://github.com/aws-samples/sample-serverless-mcp-servers/blob/main/stateless-mcp-on-lambda-nodejs/src/authorizer/index.js"
    click SLN_Transport "https://github.com/aws-samples/sample-serverless-mcp-servers/blob/main/stateless-mcp-on-lambda-nodejs/src/mcpserver/transport.js"
    click SLN_Lambda "https://github.com/aws-samples/sample-serverless-mcp-servers/blob/main/stateless-mcp-on-lambda-nodejs/src/mcpserver/mcp-server.js"
    click SLN_IaC "https://github.com/aws-samples/sample-serverless-mcp-servers/blob/main/stateless-mcp-on-lambda-nodejs/terraform/*.tf"

    click SLP_Transport "https://github.com/aws-samples/sample-serverless-mcp-servers/blob/main/stateless-mcp-on-lambda-python/src/mcpserver/server.py"
    click SLP_Lambda "https://github.com/aws-samples/sample-serverless-mcp-servers/blob/main/stateless-mcp-on-lambda-python/src/mcpserver/echo.py"
    click SLP_IaC "https://github.com/aws-samples/sample-serverless-mcp-servers/blob/main/stateless-mcp-on-lambda-python/sam/template.yaml"

    click SEC_Client "https://github.com/aws-samples/sample-serverless-mcp-servers/blob/main/stateless-mcp-on-ecs-nodejs/src/mcpclient/index.js"
    click SEC_Transport "https://github.com/aws-samples/sample-serverless-mcp-servers/blob/main/stateless-mcp-on-ecs-nodejs/src/mcpserver/transport.js"
    click SEC_Container "https://github.com/aws-samples/sample-serverless-mcp-servers/blob/main/stateless-mcp-on-ecs-nodejs/src/mcpserver/mcp-server.js"
    click SEC_ALB "https://github.com/aws-samples/sample-serverless-mcp-servers/blob/main/stateless-mcp-on-ecs-nodejs/terraform/alb.tf"
    click SEC_IaC "https://github.com/aws-samples/sample-serverless-mcp-servers/blob/main/stateless-mcp-on-ecs-nodejs/terraform/*.tf"

    click STC_Client "https://github.com/aws-samples/sample-serverless-mcp-servers/blob/main/stateful-mcp-on-ecs-nodejs/src/mcpclient/index.js"
    click STC_Transport "https://github.com/aws-samples/sample-serverless-mcp-servers/blob/main/stateful-mcp-on-ecs-nodejs/src/mcpserver/transport.js"
    click STC_Container "https://github.com/aws-samples/sample-serverless-mcp-servers/blob/main/stateful-mcp-on-ecs-nodejs/src/mcpserver/mcp-server.js"
    click STC_ALB "https://github.com/aws-samples/sample-serverless-mcp-servers/blob/main/stateful-mcp-on-ecs-nodejs/terraform/alb.tf"
    click STC_IaC "https://github.com/aws-samples/sample-serverless-mcp-servers/blob/main/stateful-mcp-on-ecs-nodejs/terraform/*.tf"

    click LOC_Server "https://github.com/aws-samples/sample-serverless-mcp-servers/blob/main/lambda-ops-mcp-server/index.js"
    click LOC_Tools "https://github.com/aws-samples/sample-serverless-mcp-servers/blob/main/lambda-ops-mcp-server/tools/*.js"
    click LOC_Utils "https://github.com/aws-samples/sample-serverless-mcp-servers/blob/main/lambda-ops-mcp-server/utils/*.js"

    %% Styles
    classDef client fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef network fill:#CCFFCC,stroke:#333,stroke-width:1px
    classDef compute fill:#CCCCFF,stroke:#333,stroke-width:1px
    classDef infra fill:#EEEEEE,stroke:#333,stroke-width:1px
```
