OpenAPI MCP Server - AWS Lambda Deployment

Serverless deployment of the AWS Labs OpenAPI MCP Server on AWS Lambda with API Gateway.

Overview

This monorepo contains three packages for deploying OpenAPI MCP servers to AWS Lambda:

• packages/mcp-server/ - Core MCP server implementation (from awslabs/mcp)
• packages/lambda-runtime/ - Lambda-specific runtime with Docker configuration
• packages/infrastructure/ - AWS CDK infrastructure code

Architecture

• Lambda Function: FastMCP server with HTTP transport via uvicorn
• API Gateway: HTTP API exposing the MCP endpoints
• Lambda Web Adapter: Native HTTP server support on Lambda (no ASGI adapter needed)
• Docker Deployment: Container image with all dependencies bundled

Prerequisites

• Python 3.12+
• uv package manager
• AWS CLI configured
• AWS CDK CLI: npm install -g aws-cdk

Local Setup

Install dependencies for the workspace:

uv sync

This will install all packages in the monorepo workspace.

Deployment

All deployment commands are available in the infrastructure package. This project uses just for task automation. Install it with:

brew install just  # macOS
cargo install just # or via cargo

1. Bootstrap CDK (first time only)

cd packages/infrastructure
just bootstrap

2. Deploy Stack

Deploy with custom API configuration using profiles (recommended):

cd packages/infrastructure

# List available profiles
just list-profiles

# Deploy using a profile
just deploy-profile zoho-crm

Or deploy with environment variables:

cd packages/infrastructure
export API_NAME=MyAPI
export API_BASE_URL=https://api.example.com
export API_SPEC_URL=https://api.example.com/openapi.json
export AUTH_TYPE=none
just deploy

Or deploy the Petstore example:

cd packages/infrastructure
just deploy-pet

Configuration Parameters

Configure via environment variables:

• API_NAME: Display name for the API (also used for stack naming)
• API_BASE_URL: Base URL of the target API
• API_SPEC_URL: URL to the OpenAPI specification (JSON or YAML)
• AUTH_TYPE: Authentication method (none, basic, bearer, api_key, cognito)

Default values (from justfile):

• API_NAME: PetstoreAPI
• API_BASE_URL: https://petstore3.swagger.io/api/v3
• API_SPEC_URL: https://petstore3.swagger.io/api/v3/openapi.json
• AUTH_TYPE: none

Stack naming: The CDK stack name is automatically generated as openapi-mcp-<api-name> (lowercase, non-alphanumeric characters except dots replaced with dashes)

Examples:

• API_NAME=PetstoreAPI → stack: openapi-mcp-petstoreapi
• API_NAME="My API" → stack: openapi-mcp-my-api
• API_NAME="API_v2.0" → stack: openapi-mcp-api-v2.0

Additional Auth Configuration

Set environment variables in cdk/openapi_mcp_stack.py for authentication:

Basic Auth:

• AUTH_USERNAME
• AUTH_PASSWORD

Bearer Token:

• AUTH_TOKEN

API Key:

• AUTH_API_KEY
• AUTH_API_KEY_NAME
• AUTH_API_KEY_IN (header/query/cookie)

Cognito:

• AUTH_COGNITO_CLIENT_ID
• AUTH_COGNITO_USERNAME
• AUTH_COGNITO_PASSWORD
• AUTH_COGNITO_USER_POOL_ID
• AUTH_COGNITO_REGION

3. Monitor Deployment

Check stack status:

cd packages/infrastructure
just status

View Lambda logs:

cd packages/infrastructure
just logs

Get the deployed API URL from CloudFormation outputs.

Testing

Test locally with Docker:

cd packages/infrastructure

# Test with a profile (all-in-one: build, run, test, cleanup)
just test-local-profile petstore

# Or step-by-step
just docker-build
just docker-run-profile zoho-crm
just test
just docker-stop

Test the deployed Lambda function:

cd packages/infrastructure

# Test with profile
just test-profile zoho-crm

# Or automatically fetch API URL from CloudFormation
just test-deployed

Or test manually with curl:

curl -X POST https://<api-url>/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

Performance Considerations

• Cold Start: ~1-2 seconds (initializes MCP server + loads OpenAPI spec)
• Warm Start: ~100-300ms (reuses server instance)
• Timeout: 30 seconds (configurable in stack)
• Memory: 512 MB (configurable in stack)

Cost Optimization

• Requests: Pay per invocation
• Memory/Duration: 512 MB x execution time
• API Gateway: HTTP API (cheaper than REST API)

Development

Package Structure

packages/
├── mcp-server/              # Core MCP server implementation
│   ├── awslabs/            # AWS Labs OpenAPI MCP server code
│   ├── tests/              # Server tests
│   └── pyproject.toml
│
├── lambda-runtime/          # Lambda deployment runtime
│   ├── lambda_handler.py   # Lambda entry point
│   ├── Dockerfile          # Container image definition
│   ├── profiles/           # API configuration profiles
│   ├── scripts/            # Helper scripts
│   └── pyproject.toml
│
└── infrastructure/          # AWS CDK infrastructure
    ├── cdk/                # CDK stack definitions
    ├── justfile            # Task automation
    └── pyproject.toml

Run MCP Server Locally

cd packages/mcp-server
uv run awslabs.openapi-mcp-server \
  --api-name MyAPI \
  --api-url https://api.example.com \
  --spec-url https://api.example.com/openapi.json

Working with Packages

Each package can be developed independently:

# Install mcp-server in development mode
cd packages/mcp-server
uv sync --extra test

# Run server tests
uv run pytest tests/ -v

# Work on lambda runtime
cd packages/lambda-runtime
# Edit Dockerfile, profiles, etc.

# Work on infrastructure
cd packages/infrastructure
# Edit CDK stacks, update justfile commands

Cleanup

Destroy the deployed stack:

cd packages/infrastructure

# Make sure API_NAME matches the deployed stack
export API_NAME=MyAPI  # or whatever you deployed
just destroy

# Or for Petstore
API_NAME=PetstoreAPI just destroy

License

This project includes code from awslabs/mcp licensed under Apache-2.0. See LICENSE and NOTICE files.