This Lambda MCP Server is a serverless implementation that exposes MCP (Model Context Protocol) tools via AWS Lambda. It leverages the awslabs.mcp_lambda_handler package to provide a stateless, scalable MCP endpoint that can be invoked from MCP clients supporting Streamable HTTP. The repository demonstrates how to define tools within a Lambda context and optionally enable session state management to persist data across consecutive tool invocations within the same conversation. To use it, install the awslabs.mcp_lambda_handler package, deploy the Lambda via your chosen serverless workflow (e.g., AWS SAM), and call the generated MCP API with Bearer token authentication as described in the README. Tools in this example include a time provider and other demo tools, such as how to increment or retrieve session-scoped counters, illustrating how session data is stored (in DynamoDB) and reused per conversation.

Prerequisites:

• AWS account with permissions to deploy Lambda and API Gateway
• AWS SAM CLI installed (optional if using SAM for deployment)
• Python 3.8+ installed
• Access to AWS services (DynamoDB, API Gateway) as needed for your deployment

Step-by-step installation and deployment:

1. Install the MCP Lambda handler package from PyPI pip install awslabs.mcp_lambda_handler

   or if you are using uv (http client) for local testing:

   uv add awslabs.mcp_lambda_handler

2. Prepare your deployment configuration (example uses AWS Lambda with SAM):

   • Create your Lambda function file that imports MCPLambdaHandler and defines tools.
   • Ensure the function handler is compatible with AWS Lambda (per the package guidance).
   • Configure an API Gateway (or use the provided SAM template) to expose the Lambda endpoint with Bearer token authentication.

3. Deploy: sam build && sam deploy --guided

   During deployment, you will be prompted to set an MCP authentication token (McpAuthToken) in the API Gateway authorizer configuration.

4. Run and test:

   • Obtain the endpoint URL from AWS after deployment.
   • Use an MCP client that supports Streamable HTTP and include the Authorization header: Bearer <your-token>.
   • Interact with the available tools (e.g., get_time, increment_counter, get_counter) as defined in your Lambda MCP server.

Notes and tips:

• The Lambda MCP server demonstrates stateful session management by persisting session data in DynamoDB per conversation via a sessionId key. Ensure you configure the MCP_SESSION_TABLE environment variable to point to your DynamoDB table or use the default name suggested in the README.
• Bearer token authentication is implemented via a simple API Gateway authorizer; for production, consider strengthening security with IAM, OAuth/JWT, or Cognito.
• The example tools include time retrieval, session counters, and weather simulation. You can extend the Lambda handler with additional tools using the provided decorator pattern from awslabs.mcp_lambda_handler.
• If you intend to run locally for testing, you may simulate AWS services (DynamoDB) with localstack or mock the session store depending on your workflow.
• This server is designed to be stateless at the Lambda layer; any persistent state should be stored in DynamoDB as shown in the session example.