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.
This project provides a working, open source based, pure AWS Lambda based Python MCP server implementation.
It contains a production grade implementation including DEPLOYMENT code with CDK and a CI/CD pipeline, testing, observability and more (see Features section).
NO Lambda adapter, no FastMCP - just pure Lambda as it was meant to be.
This project is a blueprint for new Serverless MCP servers.
It's based on AWS sample for MCP - but had major refactors since, combined with the AWS Lambda Handler cookbook template.
📜Documentation | Blogs website
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}
poetry env activate
poetry install
make deploy
Check out the official Documentation.
Make sure you have poetry v2 and above.
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 production grade 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 a production grade Python Serverless MCP server blueprint that implements best practices for AWS Lambda, MCP, Serverless CI/CD, and AWS CDK in one project.
The MCP server uses JSON RPC over HTTP (non stream-able) via API Gateway's body payload parameter. See integration tests and see how the test event is generated.
from aws_lambda_env_modeler import init_environment_variables
from aws_lambda_powertools.logging import correlation_paths
from aws_lambda_powertools.metrics import MetricUnit
from aws_lambda_powertools.utilities.typing import LambdaContext
from service.handlers.models.env_vars import McpHandlerEnvVars
from service.handlers.utils.authentication import authenticate
from service.handlers.utils.mcp import mcp
from service.handlers.utils.observability import logger, metrics, tracer
from service.logic.math import add_two_numbers
from service.mcp_lambda_handler.session_data import SessionData
@mcp.tool()
def math(a: int, b: int) -> int:
"""Add two numbers together"""
if not isinstance(a, int) or not isinstance(b, int):
raise ValueError('Invalid input: a and b must be integers')
# Uncomment the following line if you want to use session data
# session_data: Optional[SessionData] = mcp.get_session()
# call logic layer
result = add_two_numbers(a, b)
# save session data
mcp.set_session(data={'result': result})
metrics.add_metric(name='ValidMcpEvents', unit=MetricUnit.Count, value=1)
return result
@init_environment_variables(model=McpHandlerEnvVars)
@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST)
@metrics.log_metrics
@tracer.capture_lambda_handler(capture_response=False)
def lambda_handler(event: dict, context: LambdaContext) -> dict:
authenticate(event, context)
return mcp.handle_request(event, context)
The CDK code create an API GW with a path of /mcp which triggers the lambda on 'POST' requests.
The AWS Lambda handler uses a Lambda layer optimization which takes all the packages under the [packages] section in the Pipfile and downloads them in via a Docker instance.
This allows you to package any custom dependencies you might have, just add them to the Pipfile under the [packages] section.
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 aspect of a production-ready service, including:
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.
{ "mcpServers": { "aws-lambda-mcp-cookbook": { "command": "make", "args": [ "deploy" ] } } }
Related projects feature coming soon
Will recommend related projects based on sub-categories