Run Model Context Protocol Servers With AWS Lambda

What is Run Model Context Protocol Servers With AWS Lambda about?

Enables any stdio‑based MCP server—written in Python or TypeScript—to be packaged and executed inside an AWS Lambda function. Each Lambda invocation starts the server process, forwards the request, returns the response, and shuts down the process, providing a stateless, on‑demand execution model.

How to use Run Model Context Protocol Servers With AWS Lambda?

1. Package the MCP server with your Lambda code (include the server binary or npm package).
2. Define server parameters (command, args, optional env) using the library’s StdioServerParameters (Python) or a plain object (TypeScript).
3. Choose a transport layer:
   • API Gateway with OAuth (Cognito, Okta, Auth0)
   • Bedrock AgentCore Gateway
   • Lambda Function URL with SigV4
   • Direct Lambda Invoke API
4. Deploy the Lambda function and configure the chosen trigger (API Gateway, Function URL, etc.).
5. From an MCP client, call the server using the standard streamable HTTP transport or the custom transport provided by the library.

Key Features

• Universal adaptor: Works for Python (python -m …) and TypeScript (npx …) stdio servers.
• Multiple access patterns: API Gateway + OAuth, Bedrock AgentCore, Lambda URL + IAM, or direct Invoke API.
• Stateless execution: Server starts and stops per request, avoiding state‑leakage.
• Custom environment support: Pass environment variables (e.g., API keys) via Lambda configuration.
• Example catalog: Ready‑to‑deploy examples (dad‑jokes, dog‑facts, time, weather‑alerts, etc.) for both languages.

Use Cases

• Desktop IDE extensions that normally spawn local MCP servers can now call a cloud‑hosted Lambda version, enabling collaborative or distributed workflows.
• Micro‑service architectures where an MCP tool is exposed as a secure HTTP endpoint behind API Gateway or Bedrock.
• Server‑less tool integration for CI/CD pipelines, chat‑bots, or agent systems that need on‑demand tool execution without managing long‑running processes.
• Multi‑tenant SaaS offering MCP‑based tool APIs where each tenant authenticates via OAuth or IAM.

FAQ

Q: Can I use languages other than Python or TypeScript? A: The library currently only provides adapters for Python and TypeScript stdio servers. Other languages would require a custom wrapper.

Q: What happens to server state between invocations? A: The Lambda execution model is stateless; any in‑memory or on‑disk state is lost after the request finishes. Use stateless tools or external storage if persistence is needed.

Q: How are secrets (API keys, tokens) handled? A: Supply them as encrypted Lambda environment variables. Access is controlled by IAM policies; only callers with permission can invoke the function.

Q: Which authentication methods are supported? A: OAuth via API Gateway or Bedrock, AWS IAM (SigV4) for Function URLs and Invoke API.

Q: Do I need to package the MCP server binary inside the Lambda deployment package? A: Yes. Bundling the server avoids the overhead of downloading it on every invocation and ensures it runs in the constrained Lambda environment.

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.

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.

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
2. Initialize the MCP server
3. Forward the incoming request to the local server
4. Return the server's response to the function caller
5. 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.
2. The MCP Streamable HTTP transport, using Amazon Bedrock AgentCore Gateway. Authenticated using OAuth.
3. A custom Streamable HTTP transport with support for SigV4, using a Lambda function URL. Authenticated with AWS IAM.
4. 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.

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,
)

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

Use API Gateway

This solution is compatible with most MCP clients that support the streamable HTTP transport. MCP servers deployed with this architecture can typically be used with off-the-shelf MCP-compatible applications such as Cursor, Cline, Claude Desktop, etc.

You can choose your desired OAuth server provider for this solution. The examples in this repository use Amazon Cognito, or you can use third-party providers such as Okta or Auth0 with API Gateway custom authorization.

import sys
from mcp.client.stdio import StdioServerParameters
from mcp_lambda import APIGatewayProxyEventHandler, StdioServerAdapterRequestHandler

server_params = StdioServerParameters(
    command=sys.executable,
    args=[
        "-m",
        "my_mcp_server_python_module",
        "--my-server-command-line-parameter",
        "some_value",
    ],
)


request_handler = StdioServerAdapterRequestHandler(server_params)
event_handler = APIGatewayProxyEventHandler(request_handler)


def handler(event, context):
    return event_handler.handle(event, context)

See a full, deployable example here.

import {
  Handler,
  Context,
  APIGatewayProxyWithCognitoAuthorizerEvent,
  APIGatewayProxyResult,
} from "aws-lambda";
import {
  APIGatewayProxyEventHandler,
  StdioServerAdapterRequestHandler,
} from "@aws/run-mcp-servers-with-aws-lambda";

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

const requestHandler = new APIGatewayProxyEventHandler(
  new StdioServerAdapterRequestHandler(serverParams)
);

export const handler: Handler = async (
  event: APIGatewayProxyWithCognitoAuthorizerEvent,
  context: Context
): Promise<APIGatewayProxyResult> => {
  return requestHandler.handle(event, context);
};

See a full, deployable example here.

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

# Create OAuth client provider here

async with streamablehttp_client(
    url="https://abc123.execute-api.us-west-2.amazonaws.com/prod/mcp",
    auth=oauth_client_provider,
) as (
    read_stream,
    write_stream,
    _,
):
    async with ClientSession(read_stream, write_stream) as session:
        await session.initialize()
        tool_result = await session.call_tool("echo", {"message": "hello"})

See a full example as part of the sample chatbot here.

import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";

const client = new Client(
  {
    name: "my-client",
    version: "0.0.1",
  },
  {
    capabilities: {
      sampling: {},
    },
  }
);

// Create OAuth client provider here

const transport = new StreamableHTTPClientTransport(
  "https://abc123.execute-api.us-west-2.amazonaws.com/prod/mcp",
  {
    authProvider: oauthProvider,
  }
);
await client.connect(transport);

See a full example as part of the sample chatbot here.

Use Bedrock AgentCore Gateway

This solution is compatible with most MCP clients that support the streamable HTTP transport. MCP servers deployed with this architecture can typically be used with off-the-shelf MCP-compatible applications such as Cursor, Cline, Claude Desktop, etc.

You can choose your desired OAuth server provider with Bedrock AgentCore Gateway, such as Amazon Cognito, Okta, or Auth0.

Using Bedrock AgentCore Gateway in front of your stdio-based MCP server requires that you retrieve the MCP server's tool schema, and provide it in the AgentCore Gateway Lambda target configuration. AgentCore Gateway can then advertise the schema to HTTP clients and validate request inputs and outputs.

To retrieve and save your stdio-based MCP server's tool schema to a file, run:

npx @modelcontextprotocol/inspector --cli --method tools/list <your MCP server command and arguments> > tool-schema.json

# For example:
npx @modelcontextprotocol/inspector --cli --method tools/list uvx mcp-server-time > tool-schema.json

import sys
from mcp.client.stdio import StdioServerParameters
from mcp_lambda import BedrockAgentCoreGatewayTargetHandler, StdioServerAdapterRequestHandler

server_params = StdioServerParameters(
    command=sys.executable,
    args=[
        "-m",
        "my_mcp_server_python_module",
        "--my-server-command-line-parameter",
        "some_value",
    ],
)


request_handler = StdioServerAdapterRequestHandler(server_params)
event_handler = BedrockAgentCoreGatewayTargetHandler(request_handler)


def handler(event, context):
    return event_handler.handle(event, context)

See a full, deployable example here.

import { Handler, Context } from "aws-lambda";
import {
  BedrockAgentCoreGatewayTargetHandler,
  StdioServerAdapterRequestHandler,
} from "@aws/run-mcp-servers-with-aws-lambda";

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

const requestHandler = new BedrockAgentCoreGatewayTargetHandler(
  new StdioServerAdapterRequestHandler(serverParams)
);

export const handler: Handler = async (
  event: Record<string, unknown>,
  context: Context
): Promise<Record<string, unknown>> => {
  return requestHandler.handle(event, context);
};

See a full, deployable example here.

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

# Create OAuth client provider here

async with streamablehttp_client(
    url="https://abc123.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp",
    auth=oauth_client_provider,
) as (
    read_stream,
    write_stream,
    _,
):
    async with ClientSession(read_stream, write_stream) as session:
        await session.initialize()
        tool_result = await session.call_tool("echo", {"message": "hello"})

See a full example as part of the sample chatbot here.

import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";

const client = new Client(
  {
    name: "my-client",
    version: "0.0.1",
  },
  {
    capabilities: {
      sampling: {},
    },
  }
);

// Create OAuth client provider here

const transport = new StreamableHTTPClientTransport(
  "https://abc123.gateway.bedrock-agentcore.us-west-2.amazonaws.com/mcp",
  {
    authProvider: oauthProvider,
  }
);
await client.connect(transport);

See a full example as part of the sample chatbot here.

Use a Lambda function URL

This solution uses AWS IAM for authentication, and relies on granting Lambda InvokeFunctionUrl permission to your IAM users and roles to enable access to the MCP server. Clients must use an extension to the MCP Streamable HTTP transport that signs requests with AWS SigV4. Off-the-shelf MCP-compatible applications are unlikely to have support for this custom transport, so this solution is more appropriate for service-to-service communication rather than for end users.

import sys
from mcp.client.stdio import StdioServerParameters
from mcp_lambda import LambdaFunctionURLEventHandler, StdioServerAdapterRequestHandler

server_params = StdioServerParameters(
    command=sys.executable,
    args=[
        "-m",
        "my_mcp_server_python_module",
        "--my-server-command-line-parameter",
        "some_value",
    ],
)


request_handler = StdioServerAdapterRequestHandler(server_params)
event_handler = LambdaFunctionURLEventHandler(request_handler)


def handler(event, context):
    return event_handler.handle(event, context)

See a full, deployable example here.

import {
  Handler,
  Context,
  APIGatewayProxyEventV2WithIAMAuthorizer,
  APIGatewayProxyResultV2,
} from "aws-lambda";
import {
  LambdaFunctionURLEventHandler,
  StdioServerAdapterRequestHandler,
} from "@aws/run-mcp-servers-with-aws-lambda";

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

const requestHandler = new LambdaFunctionURLEventHandler(
  new StdioServerAdapterRequestHandler(serverParams)
);

export const handler: Handler = async (
  event: APIGatewayProxyEventV2WithIAMAuthorizer,
  context: Context
): Promise<APIGatewayProxyResultV2> => {
  return requestHandler.handle(event, context);
};

See a full, deployable example here.

from mcp import ClientSession
from mcp_proxy_for_aws.client import aws_iam_streamablehttp_client

async with aws_iam_streamablehttp_client(
    endpoint="https://url-id-12345.lambda-url.us-west-2.on.aws",
    aws_service="lambda",
    aws_region="us-west-2",
) as (
    read_stream,
    write_stream,
    _,
):
    async with ClientSession(read_stream, write_stream) as session:
        await session.initialize()
        tool_result = await session.call_tool("echo", {"message": "hello"})

See a full example as part of the sample chatbot here.

import { StreamableHTTPClientWithSigV4Transport } from "@aws/run-mcp-servers-with-aws-lambda";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";

const client = new Client(
  {
    name: "my-client",
    version: "0.0.1",
  },
  {
    capabilities: {
      sampling: {},
    },
  }
);

const transport = new StreamableHTTPClientWithSigV4Transport(
  new URL("https://url-id-12345.lambda-url.us-west-2.on.aws"),
  {
    service: "lambda",
    region: "us-west-2",
  }
);
await client.connect(transport);

See a full example as part of the sample chatbot here.

Use the Lambda Invoke API

Like the Lambda function URL approach, this solution uses AWS IAM for authentication. It relies on granting Lambda InvokeFunction permission to your IAM users and roles to enable access to the MCP server. Clients must use a custom MCP transport that directly calls the Lambda Invoke API. Off-the-shelf MCP-compatible applications are unlikely to have support for this custom transport, so this solution is more appropriate for service-to-service communication rather than for end users.

import sys
from mcp.client.stdio import StdioServerParameters
from mcp_lambda import stdio_server_adapter

server_params = StdioServerParameters(
    command=sys.executable,
    args=[
        "-m",
        "my_mcp_server_python_module",
        "--my-server-command-line-parameter",
        "some_value",
    ],
)


def handler(event, context):
    return stdio_server_adapter(server_params, event, context)

See a full, deployable example here.

import { Handler, Context } from "aws-lambda";
import { stdioServerAdapter } from "@aws/run-mcp-servers-with-aws-lambda";

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

export const handler: Handler = async (event, context: Context) => {
  return await stdioServerAdapter(serverParams, event, context);
};

See a full, deployable example here.

from mcp import ClientSession
from mcp_lambda import LambdaFunctionParameters, lambda_function_client

server_params = LambdaFunctionParameters(
    function_name="my-mcp-server-function",
    region_name="us-west-2",
)

async with lambda_function_client(server_params) as (
    read_stream,
    write_stream,
):
    async with ClientSession(read_stream, write_stream) as session:
        await session.initialize()
        tool_result = await session.call_tool("echo", {"message": "hello"})

See a full example as part of the sample chatbot here.

import {
  LambdaFunctionParameters,
  LambdaFunctionClientTransport,
} from "@aws/run-mcp-servers-with-aws-lambda";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";

const serverParams: LambdaFunctionParameters = {
  functionName: "my-mcp-server-function",
  regionName: "us-west-2",
};

const client = new Client(
  {
    name: "my-client",
    version: "0.0.1",
  },
  {
    capabilities: {
      sampling: {},
    },
  }
);

const transport = new LambdaFunctionClientTransport(serverParams);
await client.connect(transport);

See a full example as part of the sample chatbot here.

Related projects

• To write custom MCP servers in Lambda functions, see the MCP Lambda Handler project.
• To invoke existing Lambda functions as tools through a stdio MCP server, see the AWS Lambda Tool MCP Server project.

Considerations

• This library currently supports MCP servers and clients written in Python and Typescript. Other languages such as Kotlin are not supported.
• This library only adapts stdio MCP servers for Lambda, not servers written for other protocols such as SSE.
• This library does not maintain any MCP server state or sessions across Lambda function invocations. Only stateless MCP servers are a good fit for using this library. For example, MCP servers that invoke stateless tools like the time MCP server or make stateless web requests like the fetch MCP server. Stateful MCP servers are not a good fit, because they will lose their state on every request. For example, MCP servers that manage data on disk or in memory such as the sqlite MCP server, the filesystem MCP server, and the git MCP server.
• This library does not provide 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. 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.

Deploy and run the examples

See the development guide for instructions to deploy and run the examples in this repository.

Security

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.