AWS Lambda MCP Cookbook (Python)
This project provides a working, open source based, AWS Lambda based Python MCP server implementation.
Potencialize seu agente
Instalação do publicador. Não é um endpoint do PlugMCP.
Host a copy with our keys and logs.
Ainda não há uma versão empacotada no registro. Siga o README do repositório.
URL remota ou um comando na sua máquina? Como as duas instalações diferem
Rodar no PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDo publicador
This project provides a working, open source based, AWS Lambda based Python MCP server implementation.
This repository provides a working, deployable, open source-based, serverless MCP server blueprint with an AWS Lambda function and AWS CDK Python code with all the best practices and a complete CI/CD pipeline.
It is built on the AWS Lambda Web Adapter and the official MCP Python SDK (mcp v2), so it speaks the current 2026-07-28 MCP spec as well as older handshake-era clients.
It contains an opinionated implementation including DEPLOYMENT code with CDK and a CI/CD pipeline, testing, observability and more (see Features section).
This project is a blueprint for new Serverless MCP servers.
Contact details | mailto:[email protected]
You can start with a clean service out of this blueprint repository without using the 'Template' button on GitHub.
That's it, you are ready to deploy the MCP server (make sure Docker is running!):
cd {new repo folder}
make dev
make deploy
Check out the official Documentation.
You can also run 'make pr' will run all checks, synth, file formatters , unit tests, deploy to AWS and run integration and E2E tests.
Starting a Serverless MCP can be overwhelming. You need to figure out many questions and challenges that have nothing to do with your business domain:
This project aims to reduce cognitive load and answer these questions for you by providing an opinionated Python Serverless MCP server blueprint that implements best practices for AWS Lambda, MCP, Serverless CI/CD, and AWS CDK in one project.
This project is a blueprint for new Serverless MCP servers.
flowchart LR
agents["MCP clients<br/>agents, IDEs"]
waf["AWS WAF<br/>optional - see note"]
gw["Amazon API Gateway<br/>HTTP API v2 · ANY proxy route"]
subgraph fn["AWS Lambda · ARM64 · Python 3.14"]
direction TB
adapter["Lambda Web Adapter<br/>layer via AWS_LAMBDA_EXEC_WRAPPER"]
uvi["uvicorn on :8000"]
app["MCP server · mcp v2<br/>streamable_http_app at /mcp<br/>stateless_http · json_response"]
adapter --> uvi --> app
end
ddb[("Amazon DynamoDB<br/>provisioned for app state")]
cw["CloudWatch<br/>logs · metrics · dashboards · alarms"]
xray["AWS X-Ray"]
agents -->|"MCP over Streamable HTTP"| gw
waf -.-> gw
gw --> adapter
app -.->|"unused by default"| ddb
app --> cw
app --> xray
classDef optional stroke-dasharray: 5 5
class waf,ddb optional
AWS WAF is not attached today. WAF cannot front an API Gateway HTTP API (v2) - only a REST API.
WafToApiGatewayConstructincdk/service/waf_construct.pyis kept as a working reference: wire it up if you switch the edge to a REST API GW.DynamoDB is provisioned but unread. The
2026-07-28protocol is stateless, so nothing touches the table out of the box - see Session data and DynamoDB.
Based on AWS Lambda Web Adapter and the official MCP Python SDK (mcp v2).
Use an HTTP API GW and Lambda function. Can be used with a REST API GW with a custom domain too.
The server is a plain ASGI (Starlette) app served by uvicorn behind the Lambda Web Adapter, so it upholds the official MCP protocol and has a native auth mechanism (OAuth).
The MCP surface is split by capability kind, mirroring the business logic layout so each protocol binding sits opposite the logic it exposes:
service/
app.py the ASGI app uvicorn serves - assembles everything below
mcp_app/
mcp_server.py the MCPServer instance, its identity and instructions
caching.py cache hints advertised on catalog listings
context.py AppContext + lifespan (shared, per-process state)
handlers/
__init__.py imports the modules below - this is what registers them
tools.py -> service/logic/math.py
resources.py -> service/logic/profiles.py
prompts.py -> service/logic/hld.py
A handler binds the protocol to a logic function and declares how clients may treat it - see service/mcp_app/handlers/tools.py:
from mcp.types import ToolAnnotations
from service.handlers.utils.observability import logger
from service.logic.math import add_two_numbers
from service.mcp_app.mcp_server import mcp
@mcp.tool(
title='Add two numbers',
annotations=ToolAnnotations( # lets clients decide what may run without asking
read_only_hint=True,
idempotent_hint=True,
open_world_hint=False,
),
)
def math(a: int, b: int) -> int:
"""Add two numbers together"""
logger.info('using math tool', extra={'a': a, 'b': b})
return add_two_numbers(a, b)
Capabilities register on import.
@mcp.tool(),@mcp.resource()and@mcp.prompt()register when their module is imported, so a new handler module must be imported in service/mcp_app/handlers/init.py. Forget it and the capability is silently missing from the catalog rather than raising - the listing tests intests/integration/test_mcp_server.pyare what catch that.
streamable_http_app() serves both MCP protocol eras from the same endpoint, routed per request by the MCP-Protocol-Version header:
2026-07-28 - the current stateless spec: no initialize handshake, no Mcp-Session-Id.2025-11-25 and earlier - the handshake era, for clients that have not migrated yet.There is nothing to configure; both are always on.
The 2026-07-28 protocol is stateless: no initialize handshake, no Mcp-Session-Id, and the server runs with stateless_http=True. Nothing is carried between requests for you.
That is a protocol change, not a restriction on your application. The stack still provisions a DynamoDB table and passes its name to the Lambda as TABLE_NAME, so you can use it to store session or conversation state whenever you want it. Nothing reads it out of the box - it is there for you to build on.
The lifespan yields a shared context object, and the table is resolved from TABLE_NAME on first use and reused thereafter - so the server still boots without any environment configured. A handler reaches it through the injected Context. The approach the spec recommends is a server-minted handle: your tool writes state to DynamoDB under a key it generates, returns that key to the client, and the client passes it back as an ordinary tool argument on the next call.
from mcp.server.mcpserver import Context
@mcp.tool()
def start_analysis(dataset: str, ctx: Context) -> str:
"""Begin an analysis and return a handle to resume it."""
handle = str(uuid.uuid4())
ctx.request_context.lifespan_context.table.put_item(Item={'session_id': handle, 'dataset': dataset})
return handle
@mcp.tool()
def continue_analysis(handle: str, ctx: Context) -> str:
"""Continue an analysis previously started with start_analysis."""
state = ctx.request_context.lifespan_context.table.get_item(Key={'session_id': handle})['Item']
...
The table's partition key is session_id, and the Lambda role already grants GetItem, PutItem, UpdateItem and DeleteItem on it.
Note: a handle is a bearer token - anyone holding it can read that state. Bind it to the caller's identity rather than trusting the handle alone.
flowchart LR
subgraph sources["Monitored resources"]
direction TB
gw["HTTP API Gateway"]
fn["Lambda function"]
logs["CloudWatch Logs<br/>ERROR pattern widget"]
ddb[("DynamoDB table")]
kpi["Custom metric<br/>ValidMcpEvents"]
end
subgraph high["High level dashboard"]
direction TB
h1["API Gateway health"]
h2["Daily MCP Requests"]
end
subgraph low["Low level dashboard"]
direction TB
l1["Lambda latency, errors,<br/>throttles, invocations"]
l2["Error log widget"]
l3["DynamoDB usage, latency,<br/>errors, throttles"]
end
alarms["CloudWatch alarms<br/>5xx error rate · p90 latency"]
sns["SNS topic<br/>KMS encrypted"]
gw --> h1
kpi --> h2
fn --> l1
logs --> l2
ddb --> l3
h1 --> alarms
l1 --> alarms
l2 --> alarms
alarms --> sns
2026-07-28 spec and older clients alike.The CDK code creates an HTTP API GW that proxies every path to the Lambda, which serves MCP at /mcp.
The AWS Lambda handler uses a Lambda layer optimization: make build exports the runtime dependencies from pyproject.toml with uv export, and CDK bundles them into a layer via Docker.
To package extra dependencies, add them to the dependencies list in pyproject.toml.
The AWS Lambda handler will implement multiple best practice utilities.
Each utility is implemented when a new blog post is published about that utility.
The utilities cover multiple aspects of a well-structured service, including:
auth parameter on MCPServer for an OAuth implementation, or put an IAM/Cognito/Lambda authorizer in front of the API Gateway.421 Misdirected Request. API Gateway is where authn/authz belongs here.Code contributions are welcomed. Read this guide.
Read our code of conduct here.
This library is licensed under the MIT License. See the LICENSE file.
This repository provides a working, deployable, open source-based, serverless MCP server blueprint with an AWS Lambda function and AWS CDK Python code with all the best practices and a complete CI/CD
Visão geral
This repository provides a working, deployable, open source-based, serverless MCP server blueprint with an AWS Lambda function and AWS CDK Python code with all the best practices and a complete CI/CD pipeline.
Ferramentas
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Este registro não lista nenhuma variável de ambiente obrigatória.
Aws Lambda MCP Cookbook roda localmente via stdio.
Última verificação: 2026-10-28. This repository provides a working, deployable, open source-based, serverless MCP server blueprint with an AWS Lambda function and AWS CDK Python code with all the best practices and a complete CI/CD pipeline.