mcp-worker-starter
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 devcurl -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
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Zero-dependency Cloudflare Worker gateway turning websites and REST APIs into MCP tools.
Cloudflare Workers MCP server: ai-model-router
Cloudflare Workers MCP server: ai-token-counter
Cloudflare Workers MCP server: ai-rate-limit-tracker
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceA Cloudflare Workers-based MCP server that enables deployment of custom tools accessible via the Model Context Protocol without authentication requirements.-
- -licenseNot gradedqualityNot gradedmaintenanceAllows deploying a Model Context Protocol server on Cloudflare Workers without authentication, enabling AI assistants to access custom tools through the MCP standard.-
- FlicenseNot gradedqualityNot gradedmaintenanceA deployable server implementation of the Model Context Protocol that allows you to run custom tools on Cloudflare Workers without authentication requirements.-
- FlicenseNot gradedqualityDmaintenanceEnables deployment of a remote Model Context Protocol server on Cloudflare Workers without authentication. Allows custom tool definitions and connection from MCP clients like Claude Desktop or Cloudflare AI Playground.-