# aarora79/streamable-mcp-serverless architecture

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

- Interactive diagram: https://gitdiagram.com/aarora79/streamable-mcp-serverless
- Repository: https://github.com/aarora79/streamable-mcp-serverless

## Overview

##### Project type and purpose
- This is a server‐client tool implementing the Model Context Protocol (MCP) using a serverless backend on AWS Lambda and a TypeScript CLI client.
- The backend is containerized (Docker → ECR → Lambda) and fronted by API Gateway with HTTP streaming support.
- It demonstrates two auth flows: OAuth 2.1 via Cognito and a simple Lambda authorizer, and integrates with Amazon Bedrock for foundation model calls.

##### File structure
- Top-level scripts and configs:
- Dockerfile, build_and_push.sh (container build & push)
- deploy.py + pyproject.toml + uv.lock (Python deploy script & dependencies)
- package.json/tsconfig.json (TypeScript project config)
- src/ contains two entry points:
- server.ts (Express-style MCP server logic)
- client.ts (CLI client implementation)
- src/auth/ holds all auth logic: cognito.ts, lambdaAuth.ts, oauthMetadata.ts, lambdaAuth.ts, etc.
- Utility files: logging.js, mcpClientUtils.ts, mcpTransport.ts
- docs/ for marketing and tech collateral
- payload.json for sample requests

##### README for architecture insights
- Architecture involves API Gateway → Lambda container → ECR, Cognito, CloudWatch, and Bedrock
- Two deployment modes: OAuth via Cognito vs Lambda authorizer
- Local dev uses tsx to run server and client

##### Main components
a. Client (CLI)
b. Amazon API Gateway (HTTP API with streaming)
c. AWS Lambda (MCP server container)
- Optionally separate Lambda function for custom authorizer
d. Amazon ECR (container registry)
e. Amazon Cognito (OAuth 2.1 provider + JWKS)
f. Amazon CloudWatch Logs (request and Bedrock usage logging)
g. Amazon Bedrock (foundation model service)

##### Relationships and data flows
- Client → API Gateway: HTTP POST to /mcp (with or without Bearer token)
- API Gateway → Lambda Server: invokes container-based function
- Lambda Server ↔ Cognito: token verification, metadata discovery
- Lambda Server → Bedrock: streaming model calls
- Lambda Server → CloudWatch Logs: structured logging of requests & usage
- Deployment pipeline: build_and_push.sh → Docker image → ECR → deploy.py → Lambda

##### Architectural patterns and design principles
- Serverless microservice: no servers to manage, autoscaling via Lambda
- Containerization: consistent runtime in Lambda via ECR images
- HTTP streaming: stateful Streamable-HTTP transport per MCP spec
- Pluggable auth: strategy pattern for OAuth 2.1 vs Lambda authorizer
- Separation of concerns: transport, auth, business logic, deployment scripts

##### Essential elements to capture
- The streaming HTTP session (Mcp-Session-Id header management)
- OAuth discovery (.well-known endpoints)
- PKCE and JWT verification steps
- Fallback to Lambda authorizer path
- Logging to CloudWatch and analytics tool calling Bedrock

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef aws fill:#B3E5FC,stroke:#0288D1,stroke-width:2px
    classDef registry fill:#C8E6C9,stroke:#388E3C,stroke-width:2px
    classDef client fill:#FFE0B2,stroke:#FB8C00,stroke-width:2px
    classDef pipeline fill:#E0E0E0,stroke:#9E9E9E,stroke-width:2px
    classDef code fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px

    subgraph "AWS Account: us-east-1"
        Client["CLI Client"]:::client
        APIGW["API Gateway\n(HTTP API w/ Streaming)"]:::aws

        subgraph "MCP Server Lambda\n(Containerized MCP Server)"
            Server["MCP Server Lambda\n(server.ts)"]:::code
            AuthModule["Auth Module\n(index.ts)"]:::code
            LambdaAuth["Custom Lambda Authorizer\n(lambdaAuth.ts)"]:::code
            CognitoLogic["Cognito Logic\n(cognito.ts)"]:::code
            OAuthMeta["OAuth Metadata\n(oauthMetadata.ts)"]:::code
            Transport["Streamable-HTTP Transport\n(mcpTransport.ts)"]:::code
            Utils["MCP Client Utilities\n(mcpClientUtils.ts)"]:::code
            Logging["Structured Logging\n(logging.js)"]:::code
        end

        Cognito["Amazon Cognito\n(OAuth 2.1)"]:::aws
        CloudWatch["CloudWatch Logs"]:::aws
        Bedrock["Amazon Bedrock"]:::aws
        ECR["Amazon ECR"]:::registry
        LambdaAuthorizer["Lambda Authorizer\n(as Custom Authorizer)"]:::aws
    end

    subgraph "CI/CD Pipeline"
        Dockerfile["Dockerfile"]:::pipeline
        BuildPush["build_and_push.sh"]:::pipeline
        Deploy["deploy.py"]:::pipeline
    end

    Client -->|"POST /mcp"| APIGW
    APIGW -->|Authorizer| LambdaAuthorizer
    APIGW -->|"Invoke MCP Lambda"| Server
    LambdaAuthorizer -->|Verify & Context| Server
    Server -->|"Verify Token"| CognitoLogic
    Server -->|"Fetch .well-known"| OAuthMeta
    Server -->|"Stream calls"| Bedrock
    Server -->|"Log requests"| CloudWatch
    BuildPush -->|Uses| Dockerfile
    BuildPush -->|Push image| ECR
    ECR -->|Provides image| Server
    Deploy -->|Update Lambda| Server

    click Client "https://github.com/aarora79/streamable-mcp-serverless/blob/main/src/client.ts"
    click Server "https://github.com/aarora79/streamable-mcp-serverless/blob/main/src/server.ts"
    click LambdaAuth "https://github.com/aarora79/streamable-mcp-serverless/blob/main/src/auth/lambdaAuth.ts"
    click CognitoLogic "https://github.com/aarora79/streamable-mcp-serverless/blob/main/src/auth/cognito.ts"
    click OAuthMeta "https://github.com/aarora79/streamable-mcp-serverless/blob/main/src/auth/oauthMetadata.ts"
    click AuthModule "https://github.com/aarora79/streamable-mcp-serverless/blob/main/src/auth/index.ts"
    click Transport "https://github.com/aarora79/streamable-mcp-serverless/blob/main/src/mcpTransport.ts"
    click Utils "https://github.com/aarora79/streamable-mcp-serverless/blob/main/src/mcpClientUtils.ts"
    click Logging "https://github.com/aarora79/streamable-mcp-serverless/blob/main/src/logging.js"
    click Dockerfile "https://github.com/aarora79/streamable-mcp-serverless/tree/main/Dockerfile"
    click BuildPush "https://github.com/aarora79/streamable-mcp-serverless/blob/main/build_and_push.sh"
    click Deploy "https://github.com/aarora79/streamable-mcp-serverless/blob/main/deploy.py"
```
