Run Model Context Protocol Servers with AWS Lambda

The MCP server child process does not automatically inherit the Lambda execution role's credentials. To allow an MCP server to call AWS APIs, you must manually retrieve the credentials from the Lambda environment and pass them as environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, and AWS_REGION).

import os
import sys
import boto3
from mcp.client.stdio import StdioServerParameters

session = boto3.Session()
credentials = session.get_credentials()
if credentials is None:
    raise RuntimeError("Unable to retrieve AWS credentials from the execution environment")
resolved = credentials.get_frozen_credentials()

server_params = StdioServerParameters(
    command=sys.executable,
    args=["-m", "my_mcp_server"],
    env={
        "AWS_REGION": os.environ.get("AWS_REGION", "us-west-2"),
        "AWS_DEFAULT_REGION": os.environ.get("AWS_REGION", "us-west-2"),
        "AWS_ACCESS_KEY_ID": resolved.access_key,
        "AWS_SECRET_ACCESS_KEY": resolved.secret_key,
        "AWS_SESSION_TOKEN": resolved.token or "",
    },
)

Using Bedrock AgentCore Gateway in front of a stdio-based MCP server allows the gateway to advertise the tool schema to HTTP clients and validate request inputs/outputs.

Requirement: You must retrieve the MCP server's tool schema and provide it in the AgentCore Gateway Lambda target configuration.

Schema Retrieval

Use the MCP Inspector to extract the tool schema to a JSON file:

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

Schema Cleaning

If the schema contains incompatible types (like "items": {}, "default": null, or anyOf with {"type": "null"}), you may need to clean it using the provided script:

python3 scripts/clean-tool-schema.py tool-schema.json

Implementation

Use BedrockAgentCoreGatewayTargetHandler instead of the standard API Gateway handler.

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);
};

To deploy and run the example MCP servers, follow these prerequisite steps:

1. Install AWS CDK CLI: Ensure the AWS CDK CLI is installed.
2. Request Bedrock Model Access: Request access to Anthropic Claude 3.7 Sonnet in the us-west-2 region via the AWS Console.
3. Configure IAM Roles: Create the necessary IAM roles for Lambda functions and Bedrock AgentCore gateways using the provided policy files in the repository.
4. Bootstrap CDK: Bootstrap your AWS account for the target region.

Note: The examples default to us-west-2. If using a different region, you must perform a search-and-replace for us-west-2 in the configuration files.

aws iam create-role \
  --role-name mcp-lambda-example-servers \
  --assume-role-policy-document file://examples/servers/lambda-assume-role-policy.json

aws iam attach-role-policy \
  --role-name mcp-lambda-example-servers \
  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole

aws iam put-role-policy \
  --role-name mcp-lambda-example-servers \
  --policy-name secret-access \
  --policy-document file://examples/servers/lambda-function-role-policy.json

aws iam put-role-policy \
  --role-name mcp-lambda-example-servers \
  --policy-name sns-sqs-access \
  --policy-document file://examples/servers/lambda-function-sns-sqs-policy.json

aws iam create-role \
  --role-name mcp-lambda-example-agentcore-gateways \
  --assume-role-policy-document file://examples/servers/bedrock-agentcore-gateway-assume-role-policy.json

aws iam put-role-policy \
  --role-name mcp-lambda-example-agentcore-gateways \
  --policy-name bedrock-agentcore-full-access \
  --policy-document file://examples/servers/bedrock-agentcore-gateway-role-policy.json

cdk bootstrap aws://<aws account id>/us-west-2

You can deploy MCP servers to AWS Lambda and expose them via API Gateway using the MCP Streamable HTTP Transport. This architecture is compatible with off-the-shelf MCP clients like Cursor, Cline, and Claude Desktop. You can use Amazon Cognito, Okta, or Auth0 as your OAuth provider for authorization via API Gateway custom authorization.

Python Server Implementation

Use APIGatewayProxyEventHandler and StdioServerAdapterRequestHandler to wrap your MCP server parameters.

TypeScript Server Implementation

Use @aws/run-mcp-servers-with-aws-lambda to import APIGatewayProxyEventHandler and StdioServerAdapterRequestHandler to handle Lambda events.

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)