by mikegc-aws
Creates a simple MCP tool server with "streaming" HTTP.
# Add to your Claude Code skills
git clone https://github.com/mikegc-aws/Lambda-MCP-ServerGuides for using mcp servers skills like Lambda-MCP-Server.
No comments yet. Be the first to share your thoughts!
Top skills in this category by stars
⚠️ IMPORTANT: The Lambda MCP Server module code IS maintained, just not in this repository. It is now hosted and maintained at awslabs/mcp-lambda-handler. This repository remains as sample code of how to use the module.
To use the Lambda MCP Server, install the package directly from PyPI:
pip install awslabs.mcp_lambda_handler # or, if using uv: uv add awslabs.mcp_lambda_handler
This server requires a client that supports Streamable HTTP (not SSE). There are a few MCP clients that currently support Streamable HTTP including the MCP Inspector. There is also as a Streamable HTTP client included in this repo, built Strands Agents.
This project demonstrates a powerful and developer-friendly way to create serverless MCP (Model Context Protocol) tools using AWS Lambda. It showcases how to build a stateless, serverless MCP server with minimal boilerplate and an excellent developer experience.
In an episode of the_context, Tiffany Souterre and Mike discussed streamable HTTP for MCP as well as running (an older version of) this project:
Here is the minimal code to get an MCP server running in an AWS Lambda function:
from awslabs.mcp_lambda_handler import MCPLambdaHandler
mcp_server = MCPLambdaHandler(name="mcp-lambda-server", version="1.0.0")
@mcp_server.tool()
def get_time() -> str:
from datetime import datetime, UTC
return datetime.now(UTC).isoformat()
def lambda_handler(event, context):
return mcp_server.handle_request(event, context)
The Lambda MCP Server includes built-in session state management that persists across tool invocations within the same conversation. This is particularly useful for tools that need to maintain context or share data between calls.
Session data is stored in a DynamoDB table against a sessionId key. This is all managed for you.
Here's an example of how to use session state:
from lambda_mcp.lambda_mcp import LambdaMCPServer
session_table = os.environ.get('MCP_SESSION_TABLE', 'mcp_sessions')
mcp_server = LambdaMCPServer(name="mcp-lambda-server", version="1.0.0", session_store=session_table)
@mcp_server.tool()
def increment_counter() -> int:
"""Increment a session-based counter."""
# Get the current counter value from session state, default to 0 if not set
counter = mcp_server.session.get('counter', 0)
# Increment the counter
counter += 1
# Store the new value in session state
mcp_server.session['counter'] = counter
return counter
@mcp_server.tool()
def get_counter() -> int:
"""Get the current counter value."""
return mcp_server.session.get('counter', 0)
The session state is automatically managed per conversation and persists across multiple tool invocations. This allows you to maintain stateful information without needing additional external storage, while still keeping your Lambda function stateless.
The sample server stack uses Bearer token authentication via an Authorization header, which is compliant with the MCP standard. This provides a basic level of security for your MCP server endpoints. Here's what you need to know:
Bearer Token: When you deploy the stack, a bearer token is configured through a custom authorizer in API Gateway
Using the Bearer Token:
Authorization header with the format: Bearer <your-token>Custom Authorizer: The implementation uses a simple custom authorizer that validates a single bearer token. This can be easily extended or replaced with more sophisticated authentication systems like Amazon Cognito for production use.
⚠️ Security Note: While bearer token authentication provides a standard-compliant authentication mechanism, consider implementing additional security measures such as:
The current bearer token implementation is primarily intended for demonstration and development purposes. For production systems handling sensitive data, implement appropriate additional security measures based on your specific requirements.
This is a proof-of-concept implementation of an MCP server running on AWS Lambda, along with a Strands Agents client that demonstrates its functionality. The project consists of two main components:
The server comes with three example tools that demonstrate different use cases:
get_weather(city: str): Get the current weather for a city. Returns a simulated temperature for the given city.count_s3_buckets(): Count the number of S3 buckets in your AWS account.get_time(): Get the current UTC date and time, and show how long since last time was asked for (if session available).Before running the client, ensure you have:
Clone this repository:
git clone <repository-url>
Navigate to the server directory:
cd server-http-python-lambda
Deploy using SAM:
sam build && sam deploy --guided
Note: You will be prompted for an McpAuthToken. This is the Authorization Bearer token that will be requitred to call the endpoint. This simple implimentation uses an AWS API Gateway authorizers with the McpAuthToken passed in as an env var. This can be swapped out for a production implimentation as required.
Update the api_gateway_url and auth_token in ./client-strands-agents-mcp/main.py:
cd client-strands-agents-mcp
Navigate to the client directory:
cd client-strands-agents-mcp
Run the helper script:
uv sync
uv run main.py
The Lambda MCP Server is designed to make tool creation as simple as possible. Here's how to add a new tool:
server/app.py@mcp_server.tool()
def my_new_tool(param1: str, param2: int) -> str:
"""Your tool description.
Args:
param1: Description of param1
param2: Description of param2
Returns:
Description of return value
"""
# Your tool implementation
return f"Processed {param1} with value {param2}"
That's it! The decorator handles:
See CONTRIBUTING for more information.
For AWS security best practices, refer to the AWS Security Documentation and Amazon Bedrock security best practices.
This library is licensed under the MIT-0 License. See the LICENSE file.