Aws Serverless Mcp Server

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: 
        ▼
  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](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:

``bash 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://.execute-api..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://.execute-api..amazonaws.com/mcp"
API_KEY=""

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://.execute-api..amazonaws.com/mcp",
      "headers": { "x-api-key": "" }
    }
  }
}

Windsurf

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

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

VS Code

.vscode/mcp.json:

{
  "servers": {
    "my-server": {
      "type": "sse",
      "url": "https://.execute-api..amazonaws.com/mcp",
      "headers": { "x-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](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.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: goodandco
• Source: goodandco/aws-serverless-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.