run-model-context-protocol s-with-aws-lambda

This MCP server wrapper enables you to run stdio-based MCP servers inside AWS Lambda functions, allowing clients to communicate with those servers over the MCP protocol via short-lived HTTP transports. The library supports multiple transport patterns, including API Gateway with streamable HTTP, Bedrock AgentCore Gateway, a custom Lambda URL-based transport with SigV4, and direct Lambda Invoke-based transport. You can package your existing MCP server alongside the Lambda handler code and start it as a local stdio process within the Lambda function, then forward requests and responses between the MCP client and the server through the Lambda lifecycle. Typical use cases include running TypeScript or Python MCP servers in Lambda and exposing them to MCP clients such as desktop applications or cloud services.

Prerequisites:

• Node.js and npm or Python and pip, depending on your preferred language for the Lambda wrapper usage.
• AWS credentials configured for Lambda deployment and the chosen transport (API Gateway, Lambda URL, or direct Invoke).

Installation steps (Node.js/npm):

1. Install the MCP Lambda wrapper package locally or in your project:

npm install --save @aws/run-mcp-servers-with-aws-lambda

2. If you also maintain your own MCP server code (e.g., a TypeScript module), ensure it is available in your package or as part of the deployment package.
3. Configure and deploy the Lambda function following AWS guidelines, wiring up the desired transport (API Gateway, Lambda URL, etc.).

Installation steps (Python):

1. Install the Python package for MCP Lambda wrappers if you use the Python side:

pip install run-mcp-servers-with-aws-lambda

2. Bundle your MCP server and Lambda handler code accordingly and deploy to AWS Lambda with the desired trigger (API Gateway, Lambda URL, or direct invocation).

General deployment notes:

• Ensure the Lambda execution role has appropriate permissions for the chosen transport (e.g., API Gateway, IAM-based Lambda URL access).
• Package any dependent MCP server binaries or modules with the deployment package if needed.
• For Lambda cold starts, consider bundling dependencies to minimize startup time.

Tips and common considerations:

• If your MCP server is traditionally run with a package manager (e.g., npm, pip), you can leverage the wrapper to host it inside Lambda and invoke it on-demand.
• When using API Gateway or Lambda URL transports, you’ll typically authenticate via OAuth or IAM-based methods. Plan your authentication strategy accordingly.
• For Python servers, you may need to adjust PYTHONPATH when using Lambda layers to ensure the MCP server module is discoverable by the subprocess.
• The wrapper supports various startup modes and parameters; you’ll often determine the right command-line arguments by locally running your MCP server module and mirroring those arguments in the Lambda-adapted startup sequence.
• Monitor Lambda timeouts and memory usage to ensure your stdio MCP server has enough headroom to start and respond within the function’s invocation window.