Skip to main content
Glama
goodandco

Serverless MCP Server

by goodandco
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

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.

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/goodandco/aws-serverless-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server