mcp-worker-starter

Cloudflare Workers向けの最小限のModel Context Protocolサーバー。依存関係ゼロ、1ファイル、素のPOST。

私は本番環境でMCPサーバーを運用しており、認証されたツールを通じてClaudeに生の業務データを公開しています。これは、そのサーバーからビジネスロジックを取り除き、傷跡を残したままのものです。

MCPサーバーのハッピーパスはおよそ40行です。公開する価値があるのは、以下の3つの落とし穴です。それぞれが静かに進行し、そのうちの1つは私の2つのプロダクトを停止に追い込みました。

障害を招く405

MCPクライアントは、サーバーからプッシュされるメッセージを待ち受けるために、Accept: text/event-stream付きのGETを開きます。サーバーがSSEに対応していない場合、プロトコルは405を返すことを定めています。このステータスは「もう開かないでください」という合図です。

私はその代わりに、親切なJSONボディを添えて200を返しました。エラーよりも200の方が親切に思えたからです。

クライアントはその200を「終了したストリーム」と解釈し、再接続しました。しかも即座に。バックオフもなく、私が確認していたどこにもエラーは表示されませんでした。

1日で201,936件のリクエスト。 これでCloudflareアカウント全体の1日あたりのリクエスト枠を消費し尽くし、同じアカウントを共有していた、まったく無関係の別のプロダクトを停止に追い込みました。MCPサーバー自体は一度もエラーを記録しませんでした。サーバー側から見れば何も問題がなかったからです。201,936回、すべてのリクエストに正しく応答していたのです。

プロトコルが405を期待している場面での200は、より親切な答えではありません。それは礼儀正しい無限ループです。

if ((request.headers.get("accept") ?? "").includes("text/event-stream")) {
  return new Response(JSON.stringify({ error: "This server does not expose an SSE stream. Use POST." }), {
    status: 405,
    headers: { "content-type": "application/json; charset=utf-8", allow: "POST" },
  });
}

Related MCP server: Remote MCP Server (Authless)

通知にidはなく、ボディも返してはいけない

JSON-RPC通知はファイア・アンド・フォーゲットです。idなしで届き、呼び出し側は応答を待っていません。ここで{"jsonrpc":"2.0","result":{}}を返すと、厳格なクライアントはこのやり取りを不正なものとして扱います。誰も求めていないことに応答したからです。

空のボディを伴う202が、「受け取ったが、返すことは何もない」という正しい応答です。

if (id === undefined || id === null) return new Response(null, { status: 202 });

クライアントのprotocolVersionをエコーする

initializeでは、独自のprotocolVersionをハードコードするのではなく、クライアントが提示したprotocolVersionをそのまま返してください。ハードコードすると、今日は機能するハンドシェイクが、クライアントが更新された週に静かに機能しなくなります。クライアントが何も指定しない場合にのみ、デフォルトにフォールバックします。

使い方

npm install
npx wrangler dev

curl -s http://localhost:8787 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq

デプロイ:

npx wrangler deploy

次に、デプロイしたURLをクライアントのMCPサーバーとして追加します。これはPOSTで通信します。

独自ツールを追加する

src/index.tsのTOOLS配列を編集してください。見た目以上に重要なルールが2つあります。

• descriptionはプロンプトである。 モデルはそれを読んでツールを選びます。コードを見ることができず、スキーマを二度は読まない読者のために書きましょう。

• データを返し、散文は返すな。 モデルは、あなたがJSONで何を言いたいのかを推測するよりも、あなたのJSONをうまく説明できます。

認証とレート制限

どちらも初期状態ではオフになっており、スターターは設定なしで動作します。

トークン認証は、MCP_TOKENを設定すると有効になります。その後はリクエストにAuthorization: Bearer <token>を提示する必要があります。

npx wrangler secret put MCP_TOKEN

毎時レート制限は、KV名前空間をRATE_LIMITとしてバインドすると有効になります。デフォルトの上限は1時間あたり300リクエストです。本番環境では、グローバルではなくテナントごとに上限を設定し、呼び出し元を識別できるものに基づいてキーを付けています。

[[kv_namespaces]]
binding = "RATE_LIMIT"
id = "your-kv-namespace-id"

ここでレート制限は過剰防御ではありません。落とし穴の1つ目は、まさに上限があれば1日ではなく数分で捕捉できた障害の形です。

これは何ではないか

SDKでも、フレームワークでも、そのつもりもありません。全部入りが欲しいなら、公式のTypeScript SDKかCloudflareのAgents SDKを使ってください。

これは、サーバー全体を一気に読んで、それが何をするかを正確に理解したい場合のためのものです。

テスト

npm test

ハンドシェイク、ツールの往復、そして3つの落とし穴のそれぞれをカバーしています。いずれかの回帰は、高くつくまで見えないからです。

ライセンス

MIT