Skip to content
Back to search

Lambda-MCP-Server

Creates a simple MCP tool server with "streaming" HTTP.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mikegc-aws--lambda-mcp-server/badge.svg)](/listings/mikegc-aws--lambda-mcp-server)

HTML

<a href="/listings/mikegc-aws--lambda-mcp-server"><img src="/api/listings/mikegc-aws--lambda-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- [AWS Account](https://aws.amazon.com/free/?trk=64e03f01-b931-4384-846e-db0ba9fa89f5&sc_channel=code) with appropriate permissions - [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html?trk=64e03f01-b931-4384-846e-db0ba9fa89f5&sc_channel=code) installed - Access to [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html?trk=64e03f01-b931-4384-846e-db0ba9fa89f5&sc_channel=code) in your AWS account - [Amazon Nova Pro](https://docs.aws.amazon.com/nova/latest/userguide/what-is-nova.html?trk=64e03f01-b931-4384-846e-db0ba9fa89f5&sc_channel=code) enabled in your Amazon Bedrock model access settings

Amazon Bedrock Setup

Before running the client, ensure you have:

1. [Enabled Amazon Bedrock access](https://docs.aws.amazon.com/bedrock/latest/userguide/setting-up.html?trk=64e03f01-b931-4384-846e-db0ba9fa89f5&sc_channel=code) in your AWS account 2. [Enabled the Amazon Nova Models](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html?trk=64e03f01-b931-4384-846e-db0ba9fa89f5&sc_channel=code) in your Bedrock model access settings 3. Appropriate [IAM permissions](https://docs.aws.amazon.com/bedrock/latest/userguide/security-iam.html?trk=64e03f01-b931-4384-846e-db0ba9fa89f5&sc_channel=code) to invoke Bedrock APIs

Server Deployment

1. Clone this repository:

   git clone <repository-url>

1. Navigate to the server directory:

   cd server-http-python-lambda

1. 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](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html?trk=64e03f01-b931-4384-846e-db0ba9fa89f5&sc_channel=code) with the `McpAuthToken` passed in as an env var. This can be swapped out for a production implimentation as required.

Client Setup

1. Update the `api_gateway_url` and `auth_token` in `./client-strands-agents-mcp/main.py`:

   cd client-strands-agents-mcp

1. Navigate to the client directory:

   cd client-strands-agents-mcp

1. Run the helper script:

   uv sync
   uv run main.py

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 238 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Lambda MCP Server Demo (Streamable HTTP)
  2. > **⚠️ 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](https://github.com/awslabs/mcp/tree/main/src/mcp-lambda-handler). This repository remains as sample code of how to use the module.**
  3. >
  4. > **To use the Lambda MCP Server, install the package directly from PyPI:**
  5. >
  6. > ```bash
  7. > pip install awslabs.mcp_lambda_handler
  8. > # or, if using uv:
  9. > uv add awslabs.mcp_lambda_handler
  10. > ```
  11. > 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](https://modelcontextprotocol.io/docs/tools/inspector). There is also as a Streamable HTTP client included in this repo, built [Strands Agents](https://strandsagents.com/latest/).
  12. This project demonstrates a powerful and developer-friendly way to create serverless [MCP (Model Context Protocol)](https://github.com/modelcontextprotocol) tools using [AWS Lambda](https://aws.amazon.com/lambda/?trk=64e03f01-b931-4384-846e-db0ba9fa89f5&sc_channel=code). It showcases how to build a stateless, serverless MCP server with minimal boilerplate and an excellent developer experience.
  13. ## the_context()
  14. In an episode of [the_context](https://www.youtube.com/playlist?list=PLeAh2CQypN9V8E-pkG6ZAXj-w3dgy1qQn), Tiffany Souterre and Mike discussed streamable HTTP for MCP as well as running (an older version of) this project:
  15. <p align="center">
  16. <a href="https://youtu.be/Ejua5LQTqek">
  17. <img src="thumb.png" alt="MCP - Can Lambda do it? - Streamable HTTP Model Context Protocol" width="600" /><br>
  18. </a>
  19. </p>
  20. ## Example
  21. Here is the minimal code to get an MCP server running in an AWS Lambda function:
  22. ```python
  23. from awslabs.mcp_lambda_handler import MCPLambdaHandler
  24. mcp_server = MCPLambdaHandler(name="mcp-lambda-server", version="1.0.0")
  25. @mcp_server.tool()
  26. def get_time() -> str:
  27. from datetime import datetime, UTC
  28. return datetime.now(UTC).isoformat()
  29. def lambda_handler(event, context):
  30. return mcp_server.handle_request(event, context)
  31. ```
  32. ## Session State Management
  33. 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.
  34. Session data is stored in a DynamoDB table against a sessionId key. This is all managed for you.
  35. Here's an example of how to use session state:
  36. ```Python
  37. from lambda_mcp.lambda_mcp import LambdaMCPServer
  38. session_table = os.environ.get('MCP_SESSION_TABLE', 'mcp_sessions')
  39. mcp_server = LambdaMCPServer(name="mcp-lambda-server", version="1.0.0", session_store=session_table)
  40. @mcp_server.tool()
  41. def increment_counter() -> int:
  42. """Increment a session-based counter."""
  43. # Get the current counter value from session state, default to 0 if not set
  44. counter = mcp_server.session.get('counter', 0)
  45. # Increment the counter
  46. counter += 1
  47. # Store the new value in session state
  48. mcp_server.session['counter'] = counter
  49. return counter
  50. @mcp_server.tool()
  51. def get_counter() -> int:
  52. """Get the current counter value."""
  53. return mcp_server.session.get('counter', 0)
  54. ```
  55. 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.
  56. ## Authentication
  57. 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:
  58. 1. **Bearer Token**: When you deploy the stack, a bearer token is configured through a custom authorizer in API Gateway
  59. 2. **Using the Bearer Token**:
  60. - The client must include the bearer token in requests using the `Authorization` header with the format: `Bearer <your-token>`
  61. - The token value is provided in the stack outputs after deployment
  62. - The sample client is configured to automatically include this header when provided with the token
  63. 3. **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.
  64. ⚠️ **Security Note**: While bearer token authentication provides a standard-compliant authentication mechanism, consider implementing additional security measures such as:
  65. - AWS IAM roles and policies
  66. - OAuth 2.0 / JWT with proper token management
  67. - Amazon Cognito User Pools
  68. 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.
  69. ## What is this all about?
  70. 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:
  71. 1. **Lambda MCP Server**: A Python-based serverless implementation that makes it incredibly simple to deploy cloud hosted MCP tools.
  72. 2. **Strands Agents Client**: A demonstration client that shows how to interact with the Lambda MCP server using Strands Agents.
  73. ## Example Tools
  74. The server comes with three example tools that demonstrate different use cases:
  75. 1. `get_weather(city: str)`: Get the current weather for a city. Returns a simulated temperature for the given city.
  76. 2. `count_s3_buckets()`: Count the number of S3 buckets in your AWS account.
  77. 3. `get_time()`: Get the current UTC date and time, and show how long since last time was asked for (if session available).
  78. ## Getting Started
  79. ### Prerequisites
  80. - [AWS Account](https://aws.amazon.com/free/?trk=64e03f01-b931-4384-846e-db0ba9fa89f5&sc_channel=code) with appropriate permissions
  81. - [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html?trk=64e03f01-b931-4384-846e-db0ba9fa89f5&sc_channel=code) installed
  82. - Access to [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html?trk=64e03f01-b931-4384-846e-db0ba9fa89f5&sc_channel=code) in your AWS account
  83. - [Amazon Nova Pro](https://docs.aws.amazon.com/nova/latest/userguide/what-is-nova.html?trk=64e03f01-b931-4384-846e-db0ba9fa89f5&sc_channel=code) enabled in your Amazon Bedrock model access settings
  84. ### Amazon Bedrock Setup
  85. Before running the client, ensure you have:
  86. 1. [Enabled Amazon Bedrock access](https://docs.aws.amazon.com/bedrock/latest/userguide/setting-up.html?trk=64e03f01-b931-4384-846e-db0ba9fa89f5&sc_channel=code) in your AWS account
  87. 2. [Enabled the Amazon Nova Models](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html?trk=64e03f01-b931-4384-846e-db0ba9fa89f5&sc_channel=code) in your Bedrock model access settings
  88. 3. Appropriate [IAM permissions](https://docs.aws.amazon.com/bedrock/latest/userguide/security-iam.html?trk=64e03f01-b931-4384-846e-db0ba9fa89f5&sc_channel=code) to invoke Bedrock APIs
  89. ### Server Deployment
  90. 1. Clone this repository:
  91. ```bash
  92. git clone <repository-url>
  93. ```
  94. 1. Navigate to the server directory:
  95. ```bash
  96. cd server-http-python-lambda
  97. ```
  98. 1. Deploy using SAM:
  99. ```bash
  100. sam build && sam deploy --guided
  101. ```
  102. 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](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html?trk=64e03f01-b931-4384-846e-db0ba9fa89f5&sc_channel=code) with the `McpAuthToken` passed in as an env var. This can be swapped out for a production implimentation as required.
  103. ### Client Setup
  104. 1. Update the `api_gateway_url` and `auth_token` in `./client-strands-agents-mcp/main.py`:
  105. ```bash
  106. cd client-strands-agents-mcp
  107. ```
  108. 1. Navigate to the client directory:
  109. ```bash
  110. cd client-strands-agents-mcp
  111. ```
  112. 1. Run the helper script:
  113. ```bash
  114. uv sync
  115. uv run main.py
  116. ```
  117. ## Adding New Tools
  118. The Lambda MCP Server is designed to make tool creation as simple as possible. Here's how to add a new tool:
  119. 1. Open `server/app.py`
  120. 2. Add your new tool using the decorator pattern:
  121. ```python
  122. @mcp_server.tool()
  123. def my_new_tool(param1: str, param2: int) -> str:
  124. """Your tool description.
  125. Args:
  126. param1: Description of param1
  127. param2: Description of param2
  128. Returns:
  129. Description of return value
  130. """
  131. # Your tool implementation
  132. return f"Processed {param1} with value {param2}"
  133. ```
  134. That's it! The decorator handles:
  135. - Type validation
  136. - Request parsing
  137. - Response formatting
  138. - Error handling
  139. - MCP Documentation generation
  140. ## Notes
  141. - For production use, consider adding authentication and authorization using [AWS IAM best practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html?trk=64e03f01-b931-4384-846e-db0ba9fa89f5&sc_channel=code)
  142. ## Security
  143. See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
  144. For AWS security best practices, refer to the [AWS Security Documentation](https://docs.aws.amazon.com/security/?trk=64e03f01-b931-4384-846e-db0ba9fa89f5&sc_channel=code) and [Amazon Bedrock security best practices](https://docs.aws.amazon.com/bedrock/latest/userguide/security.html?trk=64e03f01-b931-4384-846e-db0ba9fa89f5&sc_channel=code).
  145. ## License
  146. This library is licensed under the [MIT-0 License](https://github.com/aws/mit-0). See the LICENSE file.
  147. ## Changes
  148. ### Version 2.0.0
  149. - The Lambda MCP Server module code is no longer included in this repository; it is now maintained at [awslabs/mcp-lambda-handler](https://github.com/awslabs/mcp/tree/main/src/mcp-lambda-handler).
  150. - Updated installation instructions to use the PyPI package: `pip install awslabs.mcp_lambda_handler` or `uv add awslabs.mcp_lambda_handler`.
  151. - README example code now uses the new package import and shows a minimal Lambda MCP server example.
  152. - Updated the list and descriptions of example tools to match the current implementation in `app.py`.
  153. - Updated client instructions to use Strands Agents and removed references to the TypeScript client.
  154. - Updated prerequisites and deployment instructions for clarity and accuracy.
  155. - Improved documentation for session state management and authentication.
  156. - Various documentation and usability improvements throughout the README.
  157. ### Version 1.1.0
  158. - Replaced API Key authentication with Bearer token authentication via Authorization header
  159. - Added custom authorizer to API Gateway for token validation
  160. - Updated client configuration to use bearer tokens
  161. - Made authentication system compliant with MCP standard
  162. - Added this change log section
  163. ### Version 1.0.0
  164. - Initial release
  165. - Basic MCP server implementation with AWS Lambda
  166. - Session state management with DynamoDB
  167. - Example tools implementation
  168. - TypeScript HTTP client with Amazon Bedrock integration

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.