Run Model Context Protocol (MCP) servers with AWS Lambda

This project enables you to run Model Context Protocol stdio-based servers in AWS Lambda functions.

Currently, most implementations of MCP servers and clients are entirely local on a single machine.
A desktop application such as an IDE or Claude Desktop initiates MCP servers locally as child processes
and communicates with each of those servers over a long-running stdio stream.

flowchart LR
    subgraph "Your Laptop"
        Host["Desktop Application<br>with MCP Clients"]
        S1["MCP Server A<br>(child process)"]
        S2["MCP Server B<br>(child process)"]
        Host <-->|"MCP Protocol<br>(over stdio stream)"| S1
        Host <-->|"MCP Protocol<br>(over stdio stream)"| S2
    end

This library helps you to wrap existing stdio MCP servers into Lambda functions.
You can invoke these function-based MCP servers from your application using the MCP protocol
over short-lived HTTPS connections.
Your application can then be a desktop-based app, a distributed system running in the cloud,
or any other architecture.

flowchart LR
    subgraph "Distributed System"
        App["Your Application<br>with MCP Clients"]
        S3["MCP Server A<br>(Lambda function)"]
        S4["MCP Server B<br>(Lambda function)"]
        App <-->|"MCP Protocol<br>(over HTTPS connection)"| S3
        App <-->|"MCP Protocol<br>(over HTTPS connection)"| S4
    end

Using this library, the Lambda function will manage the lifecycle of your stdio MCP server.
Each Lambda function invocation will:

1. Start the stdio MCP server as a child process
1. Initialize the MCP server
1. Forward the incoming request to the local server
1. Return the server's response to the function caller
1. Shut down the MCP server child process

This library supports connecting to Lambda-based MCP servers in four ways:

1. The MCP Streamable HTTP transport, using Amazon API Gateway. Typically authenticated using OAuth.
1. The MCP Streamable HTTP transport, using Amazon Bedrock AgentCore Gateway. Authenticated using OAuth.
1. A custom Streamable HTTP transport with support for SigV4, using a Lambda function URL. Authenticated with AWS IAM.
1. A custom Lambda invocation transport, using the Lambda Invoke API directly. Authenticated with AWS IAM.

Determine your server parameters

Many stdio-based MCP servers's documentation encourages using tools that download and run the server on-demand.
For example, uvx my-mcp-server or npx my-mcp-server.
These tools are often not pre-packaged in the Lambda environment, and it can be inefficient to
re-download the server on every Lambda invocation.

Instead, the examples in this repository show how to package the MCP server along with
the Lambda function code, then start it with python or node (or npx --offline) directly.

You will need to determine the right parameters depending on your MCP server's package.
This can often be a trial and error process locally, since MCP server packaging varies.

<details>

<summary><b>Python server examples</b></summary>

Basic example:

from mcp.client.stdio import StdioServerParameters
server_params = StdioServerParameters(

    command=sys.executable,

    args=[

        "-m",

        "my_mcp_server_python_module",

        "--my-server-command-line-parameter",

        "some_value",

    ],

)

Locally, you would run this module using:

python -m my_mcp_server_python_module --my-server-command-line-parameter some_value

Other examples:

python -m mcpdoc.cli # Note the sub-module
python -c "from mcp_openapi_proxy import main; main()"
python -c "import asyncio; from postgres_mcp.server import main; asyncio.run(main())"

If you use Lambda layers, you need to also set the PYTHONPATH for the python sub-process:

lambda_paths = ["/opt/python"] + sys.path
env_config = {"PYTHONPATH": ":".join(lambda_paths)}
server_params = StdioServerParameters(

    command=sys.executable,

    args=[

        "-c",

        "from mcp_openapi_proxy import main; main()",

    ],

    env=env_config,

)

<details>

<summary><b>Typescript server examples</b></summary>

Basic example:

const serverParams = {
  command: "npx",
  args: [
    "--offline",
    "my-mcp-server-typescript-module",
    "--my-server-command-line-parameter",
    "some_value",
  ],
};

Locally, you would run this module using:

npx --offline my-mcp-server-typescript-module --my-server-command-line-parameter some_value

Other examples:

node /var/task/node_modules/@ivotoby/openapi-mcp-server/bin/mcp-server.js

</details>

Passing credentials and other secrets to the MCP server

This library does not provide out-of-the-box mechanisms for managing any secrets needed by the wrapped
MCP server. For example, the GitHub MCP server
and the Brave search MCP server
require API keys to make requests to third-party APIs.
You may configure these API keys as
encrypted environment variables
in the Lambda function's configuration or retrieve them from Secrets Manager in the Lambda function code (examples below).
However, note that anyone with access to invoke the Lambda function
will then have access to use your API key to call the third-party APIs by invoking the function.
We recommend limiting access to the Lambda function using
least-privilege IAM policies.
If you use an identity-based authentication mechanism such as OAuth, you could also store and retrieve API keys per user but there are no implementation examples in this repository.

<details>

<summary><b>Python server example retrieving an API key from Secrets Manager</b></summary>

```python
import sys

import boto3
from mcp.client.stdio import StdioServerParameters