How mikegc-aws/lambda-mcp-server works
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