OpenAPI Lambda MCP Server

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview AWS Lambda deployment of the awslabs OpenAPI MCP Server, enabling serverless MCP (Model Context Protocol) interactions with OpenAPI-defined APIs. ## Architecture - **Source**: [awslabs/mcp](https://github.com/awslabs/mcp) openapi-mcp-server - **HTTP Server**: `lambda_handler.py` - runs FastMCP HTTP server with uvicorn - **Infrastructure**: AWS CDK deploys Docker image with AWS Lambda Web Adapter - **Transport**: API Gateway → Lambda Web Adapter → uvicorn → FastMCP ## Key Components ### HTTP Server (`lambda_handler.py`) - Runs FastMCP server as standard HTTP application using uvicorn - AWS Lambda Web Adapter handles Lambda integration transparently - No custom Lambda handlers or adapters needed - Same code works on Lambda, EC2, Fargate, and locally - Server listens on port 8080 (configured via PORT environment variable) ### CDK Stack (`cdk/openapi_mcp_stack.py`) - Deploys Lambda function as Docker image with Lambda Web Adapter - Configurable via CloudFormation parameters - Builds and deploys container image automatically - Lambda Web Adapter layer included in Docker image ### Dockerfile - Based on AWS Lambda Python 3.12 base image - Includes AWS Lambda Web Adapter extension - Uses uv for fast dependency installation - Runs HTTP server on port 8080 ### MCP Server (`awslabs/openapi_mcp_server/`) - Copied from awslabs/mcp repository - Creates MCP tools/resources from OpenAPI specs - Supports multiple auth types: none, basic, bearer, api_key, cognito, zoho ## Configuration ### API Profiles Configurations are managed using YAML profile files in the `profiles/` directory. This approach: - Keeps API configurations organized and version-controlled - Supports environment variable substitution for secrets - Enables quick switching between different APIs - Provides templates for adding new APIs Available profiles: - `petstore` - Swagger Petstore API (testing) - `zoho-crm` - Zoho CRM API v8.0 (production) - `profile-template` - Template for new APIs See `profiles/README.md` for detailed documentation. ## Commands We use `just` for task management. ```bash # Install dependencies uv sync # Run MCP server locally (stdio mode) uv run awslabs.openapi-mcp-server --api-name MyAPI --api-url https://api.example.com --spec-url https://api.example.com/openapi.json ``` ### Deployment #### Using Profiles (Recommended) ```bash # List available profiles just list-profiles # First time: bootstrap CDK just bootstrap # Deploy using a profile just deploy-profile zoho-crm # View stack status just status # View Lambda logs (auto-detects from profile) API_NAME=ZohoCRM just logs # Test deployed function just test-profile zoho-crm # Destroy stack API_NAME=ZohoCRM just destroy ``` #### Using Environment Variables (Alternative) ```bash # Deploy stack with environment variables 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 Petstore example just deploy-pet ``` Stack naming: `openapi-mcp-<api-name>` (e.g., `openapi-mcp-zohocrm`) ### Testing #### Local Testing with Profiles ```bash # Test locally 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 ``` #### Testing Deployed Lambda ```bash # Test deployed Lambda with profile just test-profile zoho-crm # Or using environment variables API_NAME=ZohoCRM just test-deployed ``` ## Important Notes - **Configuration**: Settings via YAML profiles (recommended) or environment variables (API_NAME, API_BASE_URL, API_SPEC_URL, AUTH_TYPE) - **Profiles**: Store API configurations in `profiles/` directory - see `profiles/README.md` for details - **Stack Naming**: Automatically generated as `openapi-mcp-<api-name>` (lowercase, non-alphanumeric chars except dots replaced with dashes) - **Multi-API**: Deploy multiple APIs using different profiles - each gets its own stack - Lambda cold start: ~2-3 seconds (Docker image + OpenAPI spec loading) - Warm start: ~100-300ms (HTTP server stays running between invocations) - Uses Docker image deployment (no separate layer management needed) - OpenAPI spec must be accessible from Lambda (public URL or VPC access) - Authentication credentials should use AWS Secrets Manager (not hardcoded) - Session-based HTTP transport: full MCP protocol support with state management - Lambda Web Adapter enables standard HTTP server patterns on Lambda ## License Apache-2.0 - includes code from awslabs/mcp (see LICENSE and NOTICE files)