What is Serverless Mcp Servers Cdk

serverless-mcp-servers-cdk is a project that enables the construction of a stateless MCP server on AWS Lambda using AWS CDK. It is a port of the sample-serverless-mcp-servers project.

Use cases

Use cases include building microservices, developing serverless applications, and creating APIs that require stateless interactions, particularly in scenarios where rapid deployment and scalability are essential.

How to use

To use serverless-mcp-servers-cdk, you need to install dependencies, run the MCP server and client locally for testing, and then deploy to AWS using a deployment script, npm script, or CDK command.

Key features

Key features include stateless architecture, integration with AWS Lambda and API Gateway, support for custom authentication, and the ability to deploy easily in the us-east-1 region.

Where to use

serverless-mcp-servers-cdk can be used in cloud-based applications that require scalable and serverless architecture, particularly in environments that utilize AWS services.

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 版を使用したい場合:

1. 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")),

2. デプロイ:

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"
    ]
  }
}

認証エラー

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

API Gateway カスタム認証

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

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

Hono → Express.js への切り替え

1. CDK スタック設定を変更:

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

2. 再デプロイ:

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

Express.js → Hono への切り替え

1. Hono サーバーをビルド:

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

2. CDK スタック設定を変更:

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

3. 再デプロイ:

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

🧹 クリーンアップ

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

cdk destroy --region us-east-1

MCP について詳しく学ぶ

• イントロダクション
• プロトコル仕様