How aarora79/streamable-mcp-serverless works
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