Stateless MCP Server on AWS Lambda (CDK 版)

このプロジェクトは、AWS CDK を使用して AWS Lambda と API Gateway 上でステートレスな MCP サーバーを構築します。 sample-serverless-mcp-serversの CDK 移植版で、Express.js と Hono (TypeScript) の 2 つの実装を提供します。

前提条件

AWS CLI (設定済み)
Node.js 22.x と npm
AWS CDK

📦 セットアップ手順

1. 依存関係のインストール

# メインプロジェクトの依存関係
npm install

# MCP クライアント
(cd src/js/mcpclient && npm install)

# Hono TypeScript MCP サーバー (推奨)
(cd src/ts/mcpserver && npm install)

# Express.js MCP サーバー (オプション)
(cd src/js/mcpserver && npm install)

🚀 デプロイ手順

Hono TypeScript 版のデプロイ (推奨)

現在の CDK スタックは Hono 版を使用するよう設定されています。

# 1. Hono MCP サーバーをビルド
(cd src/ts/mcpserver && npm run build)

# 2. CDKスタックをデプロイ
npm run build
cdk deploy --region us-east-1

Express.js 版への切り替え

Express.js 版を使用したい場合:

lib/serverless-mcp-servers-cdk-stack.ts:33 を編集:

// Hono版 (デフォルト)
code: lambda.Code.fromAsset(path.join(__dirname, "../src/ts/mcpserver/dist")),

// Express版に変更
code: lambda.Code.fromAsset(path.join(__dirname, "../src/js/mcpserver")),

デプロイ:

npm run build
cdk deploy --region us-east-1

🔧 ローカル開発・テスト

Hono TypeScript サーバー

# 開発サーバー起動 (ホットリロード付き)
(cd src/ts/mcpserver && npm run dev)

# または手動ビルド・実行
(cd src/ts/mcpserver && npm run build && npm start)

Express.js サーバー

node src/js/mcpserver/index.js

クライアントテスト

# ローカルサーバーをテスト
node src/js/mcpclient/index.js

# デプロイ済みサーバーをテスト
export MCP_SERVER_ENDPOINT=$(aws cloudformation describe-stacks --stack-name ServerlessMcpServersCdkStack --region us-east-1 --query "Stacks[0].Outputs[?OutputKey=='McpEndpoint'].OutputValue" --output text)
node src/js/mcpclient/index.js

Claude & Cursor での設定

{
  "servers-local": {
    "url": "http://localhost:3000/mcp",
    "headers": {
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
  },
  "servers-remote": {
    "url": "https://{{OutputValue}}.execute-api.us-east-1.amazonaws.com/dev/mcp",
    "headers": {
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
  }
}

⚠️ 重要な注意点

リージョン制限: 必ず us-east-1 リージョンにデプロイしてください (Lambda Web Adapter layer の制約)
Hono ビルド必須: Hono 版をデプロイする前に必ず npm run build を実行してください
デプロイ時間: API Gateway のエンドポイントが利用可能になるまで約 1 分かかる場合があります

📋 利用可能な機能

MCP Tools

ping: レスポンス時間テスト (100ms/1000ms で交互に切り替わり)
start-notification-stream: 定期通知テスト (Hono 版のみ)

MCP Resources

greeting-resource: 静的グリーティングリソース

MCP Prompts

greeting-template: パーソナライズされたグリーティングプロンプト

認証機能

Bearer Token 認証

MCP サーバーは Bearer Token 認証をサポートしています。環境変数 MCP_AUTH_TOKEN を設定することで認証を有効にできます。

環境変数の設定

# ローカル開発時
export MCP_AUTH_TOKEN="your-secret-token"
(cd src/ts/mcpserver && npm run dev)

# または .env ファイルで設定
echo "MCP_AUTH_TOKEN=your-secret-token" > src/ts/mcpserver/.env

# AWS Lambda環境変数として設定
# CDKスタックを編集して environment プロパティに追加:
environment: {
  AWS_LWA_PORT: "3000",
  AWS_LAMBDA_EXEC_WRAPPER: "/opt/bootstrap",
  MCP_AUTH_TOKEN: "your-production-token"
}

クライアントでの認証

# mcp-remoteクライアントでの使用例
npx mcp-remote --header "Authorization:Bearer your-secret-token" http://localhost:3000/mcp

Claude & Cursor 設定例:

{
  "example-authenticated": {
    "command": "/path/to/npx",
    "args": [
      "mcp-remote",
      "--header",
      "Authorization:Bearer your-secret-token",
      "https://{{OutputValue}}.execute-api.us-east-1.amazonaws.com/dev/mcp"
    ]
  }
}

認証エラー

認証に失敗した場合、以下のレスポンスが返されます:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "Unauthorized: Bearer token required" // または "Unauthorized: Invalid token"
  },
  "id": null
}

API Gateway カスタム認証

このサンプルには、API Gateway カスタム認証機能も含まれています。デフォルトでは無効になっていますが、CDK スタックファイル内のコメントを解除することで有効にできます。

🔄 アーキテクチャの切り替え

Hono → Express.js への切り替え

CDK スタック設定を変更:

// lib/serverless-mcp-servers-cdk-stack.ts:33
code: lambda.Code.fromAsset(path.join(__dirname, "../src/js/mcpserver")), // Express

再デプロイ:

npm run build
cdk deploy --region us-east-1

Express.js → Hono への切り替え

Hono サーバーをビルド:

(cd src/ts/mcpserver && npm run build)

CDK スタック設定を変更:

// lib/serverless-mcp-servers-cdk-stack.ts:33
code: lambda.Code.fromAsset(path.join(__dirname, "../src/ts/mcpserver/dist")), // Hono

再デプロイ:

npm run build
cdk deploy --region us-east-1

🧹 クリーンアップ

評価が終わったら、以下のコマンドで AWS リソースを削除してください:

cdk destroy --region us-east-1

Serverless CDK