Serverless MCP Server

A minimal, production-ready example of an MCP (Model Context Protocol) server running on AWS Lambda with Streamable HTTP transport, deployed behind API Gateway HTTP API v2.

Built with the official @modelcontextprotocol/sdk — no stdio adapters, no proxies.

Architecture

AI Client (Cursor / Windsurf / Claude Code / VS Code)
        │
        │  POST /mcp   x-api-key: <key>
        ▼
  API Gateway HTTP API v2
        │
        ├─ Lambda Authorizer  ←  validates x-api-key against Secrets Manager
        │
        ▼
  Lambda (Docker image, Node.js 22)
        │
        │  Lambda Web Adapter translates Lambda events → HTTP
        ▼
  Node.js HTTP server  (MCP SDK StreamableHTTPServerTransport)

Stateless by design — each request creates a fresh MCP server + transport instance. No session state, no DynamoDB, no cold-start coordination needed.

Stack

Layer	Technology
Infrastructure	AWS CDK v2 (TypeScript)
API	API Gateway HTTP API v2
Runtime	Lambda — Docker image (Node.js 22)
Authorizer	Lambda — NodejsFunction esbuild bundle (Node.js 22)
Auth	API key stored in Secrets Manager, validated per-request
MCP transport	StreamableHTTPServerTransport (stateless, JSON response mode)
Lambda ↔ HTTP bridge	AWS Lambda Web Adapter

Included sample tools

Tool	Description
get_weather	Returns mock weather for a city
calculate	Basic arithmetic (add / subtract / multiply / divide)
get_server_status	Server status, timestamp, AWS region
lookup_user	Mock user lookup by ID

Replace these with your real tool implementations in app/src/server.ts.

Prerequisites

• Node.js 22+
• Docker (running)
• AWS CLI configured — aws sts get-caller-identity should succeed
• CDK bootstrapped in your target region:

  npx cdk bootstrap aws://YOUR_ACCOUNT_ID/YOUR_REGION
  

Setup

1. Install dependencies

npm install
cd app && npm install && cd ..
cd lib/authorizer && npm install && cd ../..

2. Configure your API key

cp .env.example .env

Generate a strong key and paste it into .env:

openssl rand -hex 32
# → paste output as API_KEY=... in .env

3. Deploy

npx cdk deploy

CDK builds the Docker image, pushes to ECR, creates the Lambda functions, wires up API Gateway, and stores your key in Secrets Manager. The endpoint URL is printed as output:

Outputs:
McpServerStack.McpEndpoint = https://<id>.execute-api.<region>.amazonaws.com/mcp

Local testing

cd app && npm run build && node dist/server.js

# Initialize
curl -s -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"clientInfo":{"name":"test","version":"1.0"},"protocolVersion":"2025-03-26","capabilities":{}},"id":1}' | jq .

# List tools
curl -s -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":2}' | jq .

# Call a tool
curl -s -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_weather","arguments":{"city":"Kyiv"}},"id":3}' | jq .

Testing the deployed endpoint

MCP_URL="https://<id>.execute-api.<region>.amazonaws.com/mcp"
API_KEY="<your key from .env>"

curl -s -X POST "$MCP_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-api-key: $API_KEY" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' | jq .

# Should return 403
curl -s -X POST "$MCP_URL" \
  -H "Content-Type: application/json" \
  -H "x-api-key: wrong-key" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":2}'

For interactive debugging, use MCP Inspector:

npx @modelcontextprotocol/inspector

Select Streamable HTTP, enter the endpoint URL, add x-api-key header.

Connecting clients

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "my-server": {
      "url": "https://<id>.execute-api.<region>.amazonaws.com/mcp",
      "headers": { "x-api-key": "<API_KEY>" }
    }
  }
}

Windsurf

~/.windsurf/mcp.json (or workspace .windsurf/mcp.json):

{
  "mcpServers": {
    "my-server": {
      "url": "https://<id>.execute-api.<region>.amazonaws.com/mcp",
      "headers": { "x-api-key": "<API_KEY>" }
    }
  }
}

VS Code

.vscode/mcp.json:

{
  "servers": {
    "my-server": {
      "type": "sse",
      "url": "https://<id>.execute-api.<region>.amazonaws.com/mcp",
      "headers": { "x-api-key": "<API_KEY>" }
    }
  }
}

VS Code uses "type": "sse" — it does not yet support "type": "http" (Streamable HTTP).

Claude Code

claude mcp add my-mcp-server --transport sse "$MCP_URL" \
  --header "x-api-key: $API_KEY"

Adding your own tools

Edit app/src/server.ts and add tools inside createMcpServer():

server.tool(
  "my_tool",
  "What this tool does",
  { param: z.string().describe("A parameter") },
  async ({ param }) => ({
    content: [{ type: "text", text: `Result for ${param}` }],
  })
);

Then redeploy with npx cdk deploy.

Cleanup

npx cdk destroy

Why Lambda Web Adapter?

StreamableHTTPServerTransport expects standard Node.js IncomingMessage/ServerResponse objects, not Lambda's JSON event format. Lambda Web Adapter runs as a Lambda extension and transparently translates Lambda invocations into HTTP requests to the local server — no application code changes needed.

Why stateless?

Lambda instances are ephemeral and may not be reused between requests. Stateful MCP sessions (with session IDs) would require persisting transport state externally (e.g. DynamoDB), adding complexity. Stateless mode (sessionIdGenerator: undefined) makes each request fully self-contained — a natural fit for Lambda.

Note: API Gateway HTTP API v2 has a hard 30-second integration timeout. All tool calls must complete within this window.