2026 年 10 月時点、Workers のリモート MCP サーバーは agents の createMcpHandler（ステートレス）で作り、McpAgent は新規には使いません。認証は workers-oauth-provider の OAuthProvider で /mcp を包み、Claude Code からは claude mcp add --transport http で接続します。
SNSでシェアして、他のエンジニアにも教えてあげましょう
Cloudflare Workers でリモート MCP サーバーを作るなら、2026 年 10 月時点では agents パッケージの createMcpHandler（ステートレスなハンドラー）を使います。これまで定番だった McpAgent は 2026 年 7 月に非推奨・機能凍結になりました1。認証は @cloudflare/ の OAuthProvider で / を包むだけで OAuth 2.1 になり、Claude Code からは claude mcp add --transport http でつながります。この記事では、テンプレートからの作成、OAuth での保護、wrangler dev と curl での確認、Claude Code からの接続までを、筆者が手元で実行した結果つきで説明します。
リモート MCP サーバーは、インターネット越しに HTTP で呼べる MCP（Model Context Protocol、AI とツールをつなぐ標準プロトコル）サーバーです。手元で npx 起動する stdio 型と違い、URL を渡すだけでチームの誰の Claude Code からも同じツールを使えます。
Cloudflare の公式ドキュメントは、リモート接続の標準の通信方式を Streamable HTTP（1 つの HTTP エンドポイントで双方向にやり取りする方式）とし、SSE（Server-Sent Events）方式は非推奨としています2。Workers で作ると、次の点が楽になります。
wrangler deploy 1 回で https:/ に公開できる3initialize ハンドシェイクが不要になり、リクエスト単位で完結する Workers と相性がよくなった4workers-oauth-provider が認可サーバーの役（クライアント登録・トークン発行・検証）を引き受ける5全体の流れは次の図のとおりです。Claude Code は最初トークン無しで / を叩き、401 の応答から認可サーバーを見つけて、ブラウザで同意したあとトークン付きで呼び直します。
理由は、2026 年 7〜8 月に MCP 仕様と Cloudflare の SDK が大きく変わったからです。2025 年に書かれた記事のコード（McpAgent と /）は、今から新しく作るには勧められません。
| 時期 | 出来事 |
|---|---|
| 2026-07-27 | Agents SDK v0.20.0 が MCP 仕様 2026-07-28 に対応。createMcpHandler が SDK v2 のサーバーを作る関数（ファクトリ）を受け取る形になり、McpAgent は機能凍結1 |
| 2026-07-28 | Cloudflare のドキュメントが「新しい McpAgent サーバーは作らず、ステートレスな createMcpHandler を使う」と明記2 |
| 2026-08-06 | Cloudflare ブログが新仕様を解説。ハンドシェイクと Mcp-Session-Id の廃止、server/、Mcp-Method / Mcp-Name ヘッダー、動的クライアント登録（DCR）の非推奨化など4 |
検索の関心も落ちていません。Google トレンド（日本・過去 90 日、2026-10-05 取得）の相対値で、「MCP サーバー」は直近 4 週の平均が 5.0、その前の 8 週の平均が 4.8 とほぼ同じ水準を保ちました。「Cloudflare Workers」は 2.0 と 0.8 で、値は小さいものの上向きです6。
| 語 | 前8週 | 直近4週 |
|---|---|---|
| MCP サーバー | 4.8 | 5 |
| Cloudflare Workers | 0.8 | 2 |
| Hono | 0.8 | 2.7 |
| AWS Lambda | 1.9 | 2.3 |
Cloudflare 公式の MCP サーバーを使う側の話は Cloudflare の MCP サーバー（Code Mode）を Claude Code につなぐ にまとめています。この記事は「自分で作る側」です。
新しく作るなら createMcpHandler 一択です。違いは「プロトコルのセッションを Durable Object（状態を持つ Workers の実行単位）に持つかどうか」です。
| 項目 | createMcpHandler（推奨） | McpAgent（非推奨） |
|---|---|---|
| 状態 | ステートレス。リクエストごとにサーバーを作る | Durable Object にセッションを持つ |
| 対応仕様 | MCP 2026-07-28 と、従来のクライアントのステートレスな要求7 | 従来の仕様 |
| 必要な設定 | Workers だけ（Durable Object のバインディング不要） | Durable Object のバインディングとマイグレーション |
| 公式の扱い | 新規はこちら2 | 機能凍結。削除時期は未発表1 |
| アプリのデータ | Durable Objects・D1・KV・R2 に明示的に置く8 | セッションの状態に置けた |
createMcpHandler の主なオプションは次のとおりです（2026 年 10 月時点のドキュメント）7。
| オプション | 既定値 | 用途 |
|---|---|---|
route | "/ | MCP を受けるパス |
legacy | "stateless" | 従来のクライアントを受けるか（"reject" で拒否） |
responseMode | "auto" | "json" / "sse" で応答形式を固定 |
allowedHostnames | localhost か workers.dev | カスタムドメインで公開するときに足す |
allowedHostnames の既定は localhost と workers.dev なので、独自ドメインで公開するときは忘れずに足してください。
まず認証なしの最小構成を作り、ツールが見えることを確かめます。前提は Node.js 24（筆者は v24.6.0）です。
npm create cloudflare@latest -- remote-mcp-server-authless --template=cloudflare/ai/demos/remote-mcp-authless
cd remote-mcp-server-authless
このコマンドは公式ガイドのものです3。2026-10-05 に作ると、src/ はすでに createMcpHandler と @modelcontextprotocol/（MCP の TypeScript SDK v2）を使う形になっていました。要点だけ抜き出すと次のとおりです。
import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";
import { z } from "zod";
function createServer() {
const server = new McpServer({ name: "Authless Calculator", version: "1.0.0" });
server.registerTool(
"add",
{ inputSchema: z.object({ a: z.number(), b: z.number() }) },
async ({ a, b }) => ({ content: [{ type: "text", text: String(a + b) }] }),
);
return server;
}
const handler = createMcpHandler(createServer);
export default {
fetch(request: Request, env: Env, ctx: ExecutionContext) {
return handler(request, env, ctx);
},
} satisfies ExportedHandler<Env>;
ポイントは 3 つです。
createServer はサーバーを返す関数で、リクエストのたびに呼ばれる。グローバル変数に状態を置かないserver.registerTool(名前, { description, inputSchema }, 処理) で登録する。SDK v1 の server.tool() ではない8wrangler.jsonc に Durable Object の設定は要らない型チェックとデプロイの予行演習は次のコマンドで通りました（Wrangler 4.147.0）。
npx tsc --noEmit
npx wrangler deploy --dry-run
# Total Upload: 1208.02 KiB / gzip: 207.08 KiB
# No bindings found.
# --dry-run: exiting now.
npx wrangler dev で起動し、curl で tools/ を送ります。MCP 2026-07-28 版では、リクエストごとに MCP-Protocol-Version ヘッダーと、params._meta にプロトコルの版・クライアント情報を入れます。_meta が無いと、サーバーは「必要な _meta が無い」という Invalid params エラーを返しました。
curl -s http://localhost:8787/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2026-07-28' \
-H 'Mcp-Method: tools/list' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{"_meta":{
"io.modelcontextprotocol/protocolVersion":"2026-07-28",
"io.modelcontextprotocol/clientInfo":{"name":"curl","version":"1.0.0"},
"io.modelcontextprotocol/clientCapabilities":{}}}}'
筆者の環境では 8787 番が別のプロセスに使われていたため、--port 8931 で起動して確かめました。応答は次のとおりです（JSON Schema の中身は一部省略）。
{"result":{"tools":[{"name":"add","inputSchema":{"type":"object","properties":{"a":{"type":"number"},"b":{"type":"number"}},"required":["a","b"]}},{"name":"calculate","inputSchema":{...}}],"resultType":"complete","ttlMs":0,"cacheScope":"private","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"Authless Calculator","version":"1.0.0"}}},"jsonrpc":"2.0","id":2}
ttlMs と cacheScope は、新仕様で入ったキャッシュのヒントです4。同じ方法で server/ を送ると "supportedVersions":["2026-07-28"] が返り、tools/ で add に 2 と 3 を渡すと "text":"5" が返りました。
従来の仕様のクライアント向けに、initialize（protocolVersion: "2025-11-25"）を送っても serverInfo が返り、そのまま tools/ も通りました。1 つの / で新旧両方のクライアントを受けられるというドキュメントの説明どおりです7。
ブラウザで確かめたいときは、公式ガイドのとおり MCP Inspector を使えます3。
npx @modelcontextprotocol/inspector@latest
# 開いた画面で http://localhost:8787/mcp に接続する
公開する MCP サーバーには認証を付けます。OAuthProvider で Worker 全体を包むと、/ にはトークンを検証済みのリクエストだけが届き、それ以外のパス（/ など）は自分で書くハンドラーに回ります5。
npm i agents@0.26.0 @modelcontextprotocol/server@2.0.0 @cloudflare/workers-oauth-provider@1.2.1 zod@4
npm i -D wrangler typescript
agents@0.26.0 は @modelcontextprotocol/ を 2.0.0 ちょうどで peer 依存にしています。最新の 2.3.0 を入れると npm i が ERESOLVE で止まりました（2026-10-05 時点）。
workers-oauth-provider は、トークンと認可コードを OAUTH_KV という名前で束ねた KV に保存します5。
npx wrangler kv namespace create "OAUTH_KV"
// wrangler.jsonc（抜粋）
{
"name": "my-remote-mcp",
"main": "src/index.ts",
"compatibility_date": "2026-07-02",
"compatibility_flags": ["nodejs_compat"],
"kv_namespaces": [{ "binding": "OAUTH_KV", "id": "<KV の ID>" }],
"dev": { "port": 8788 }
}
ログインしたユーザーは getMcpAuthContext() で取れます。props には、同意のときに completeAuthorization() へ渡した値が入ります9。
import { McpServer } from "@modelcontextprotocol/server";
import { getMcpAuthContext } from "agents/mcp/server";
import { z } from "zod";
export function createServer() {
const server = new McpServer({ name: "my-remote-mcp", version: "1.0.0" });
server.registerTool(
"add",
{ description: "2 つの数を足す", inputSchema: z.object({ a: z.number(), b: z.number() }) },
async ({ a, b }) => ({ content: [{ type: "text", text: String(a + b) }] }),
);
server.registerTool(
"whoami",
{ description: "OAuth でログインしたユーザーを返す", inputSchema: z.object({}) },
async () => {
const auth = getMcpAuthContext();
const userId = (auth?.props.userId as string | undefined) ?? "anonymous";
return { content: [{ type: "text", text: `userId: ${userId}` }] };
},
);
return server;
}
workers-oauth-provider 1.x では resourceMetadata.resource（クライアントが接続する URL）が必須です。これが全トークンの宛先（audience）になります。http はループバック（localhost）だけで許されるので、本番では https:/ に書き換えます5。
import OAuthProvider, { type OAuthHelpers } from "@cloudflare/workers-oauth-provider";
import { createMcpHandler } from "agents/mcp/server";
import { createServer } from "./server";
type AuthEnv = Env & { OAUTH_PROVIDER: OAuthHelpers };
// MCP クライアントが接続する URL。トークンの宛先（audience）になる
const MCP_RESOURCE = "http://localhost:8788/mcp";
const mcpHandler = createMcpHandler(createServer);
// /authorize（同意画面）。本番ではここで GitHub などにサインインさせる
const authHandler: ExportedHandler<AuthEnv> = {
async fetch(request, env) {
if (new URL(request.url).pathname !== "/authorize") return new Response("Not found", { status: 404 });
const oauth = env.OAUTH_PROVIDER;
if (request.method === "GET") {
const authReq = await oauth.parseAuthRequest(request);
const details = await oauth.describeConsent(authReq);
const consent = await oauth.beginConsent(authReq);
consent.headers.set("Content-Type", "text/html; charset=utf-8");
const esc = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
const html = `<!doctype html><meta charset="utf-8">
<h1>${esc(details.clientName)} に MCP サーバーへのアクセスを許可しますか？</h1>
<p>送り先: ${esc(details.redirectHost)}</p>
<form method="post">
<input type="hidden" name="handle" value="${esc(consent.handle)}">
<button name="decision" value="approve">許可</button>
<button name="decision" value="deny">拒否</button>
</form>`;
return new Response(html, { headers: consent.headers });
}
const form = await request.formData();
const handle = String(form.get("handle"));
if (form.get("decision") !== "approve") {
const denied = await oauth.denyConsent(request, handle);
return new Response(null, { status: 302, headers: denied.headers });
}
const approved = await oauth.approveConsent(request, handle);
const userId = "demo-user"; // 本番ではサインインしたユーザーの ID
const { redirectTo } = await oauth.completeAuthorization({
request: approved.request,
userId,
metadata: {},
scope: approved.request.scope,
props: { userId },
});
approved.headers.set("Location", redirectTo);
return new Response(null, { status: 302, headers: approved.headers });
},
};
export default new OAuthProvider<AuthEnv>({
apiRoute: "/mcp",
apiHandler: { fetch: (req, env, ctx) => mcpHandler(req, env, ctx) },
defaultHandler: authHandler,
authorizeEndpoint: "/authorize",
tokenEndpoint: "/token",
clientRegistrationEndpoint: "/register",
resourceMetadata: { resource: MCP_RESOURCE, authorization_servers: [new URL(MCP_RESOURCE).origin] },
});
同意画面の作りは、ライブラリ同梱の「consent page」ドキュメントに沿っています。クライアント名は攻撃者が決められる値なのでエスケープし、beginConsent() が返すヘッダー（フレーム埋め込みの禁止とブラウザに結びついた Cookie）を必ず付けます。
このコードは npx tsc --noEmit と npx wrangler deploy --dry-run を通りました（Total Upload: 1428.94 KiB /）。
wrangler dev で起動し（筆者は 8932 番で確認）、トークン無しで / を叩くと 401 が返ります。WWW-Authenticate の resource_metadata が、クライアントが認可サーバーを探す入口です。
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="OAuth", resource_metadata="http://localhost:8932/.well-known/oauth-protected-resource/mcp"
続けて、curl で次の順に実行しました。
/ にクライアントを登録（DCR）→ client_id が返るcode_challenge を付けて / を GET → 上の同意画面の HTML が返るLocation ヘッダーで http:/ に code と state、iss を付けてリダイレクトされる/ に code と code_verifier を送る → token_type: bearer、expires_in: 3600、refresh_token が返るAuthorization: Bearer <トークン> で tools/ の whoami を呼ぶ → "text":"userId: demo-user"/ の応答では、code_challenge_methods_supported が ["S256"]、registration_endpoint が / でした。
Claude Code では、HTTP の MCP サーバーを次のコマンドで追加します10。
# 自分だけ（既定の local スコープ）
claude mcp add --transport http my-remote-mcp https://my-remote-mcp.<サブドメイン>.workers.dev/mcp
# チームで共有（プロジェクトの .mcp.json に書かれる）
claude mcp add --transport http --scope project my-remote-mcp https://my-remote-mcp.<サブドメイン>.workers.dev/mcp
OAuth が必要なサーバーは、Claude Code の中で / を開くか、シェルで claude mcp login <名前> を実行するとブラウザが開きます。トークンは安全に保存され、自動で更新されます10。
筆者は認証なし版を --scope project で追加し、claude -p で呼べることを確かめました（Claude Code 2.1.289）。
claude mcp add --transport http --scope project calc http://localhost:8931/mcp
# Added HTTP MCP server calc with URL: http://localhost:8931/mcp to project config
claude -p "calc の add ツールで 2 と 3 を足して、結果だけ答えて" \
--mcp-config .mcp.json --strict-mcp-config --allowedTools "mcp__calc__add"
# 5
.mcp.json に書いたプロジェクトスコープのサーバーは、最初に claude を起動したときに承認するまで Pending approval と表示されます。claude mcp list で状態を確かめてから使ってください。
本番に出すときは次の順で進めます3。
npx wrangler kv namespace create "OAUTH_KV" # 出た ID を wrangler.jsonc に書く
# src/index.ts の MCP_RESOURCE を https://<名前>.<サブドメイン>.workers.dev/mcp に変える
npx wrangler deploy
自作のリモート MCP サーバーが役に立つのは、「社内にしかない情報や操作」を Claude Code に渡したいときです。
| 場面 | ツールの例 | 置き場所 |
|---|---|---|
| 設計 | 社内 API の仕様書や ADR を検索する search_docs | R2 や D1 に置いた文書を読む |
| 実装 | 開発用 DB のスキーマを返す describe_table | D1 |
| レビュー | 社内のコーディング規約を返す get_guideline | KV |
| 運用 | 検証環境のフラグを切り替える toggle_flag | Durable Objects |
ステートレスになったので、ツールの処理で使うデータは D1・KV・R2・Durable Objects に明示的に置きます。公式の移行ガイドも、プロトコルのセッション ID ではなく、アプリが発行したハンドルでデータを指すよう勧めています8。
Workers 自体の作り方は Claude Code で Cloudflare Workers アプリを作る全手順 を、Go で MCP サーバーを書く場合は Go で MCP サーバーを作る：公式 Go SDK 入門 を、状態を持つエージェントそのものを作るなら Cloudflare Agents SDK で AI エージェントを作る を参照してください。
| 症状 | 原因 | 対処 |
|---|---|---|
npm i が ERESOLVE で止まる | agents@0.26.0 が @modelcontextprotocol/ を peer 依存で固定 | @modelcontextprotocol/ を指定して入れる |
Property 'resourceMetadata' is missing | workers-oauth-provider 1.x で必須になった | resourceMetadata: { resource: "…/ を足す |
Invalid params: … missing the required per-request envelope key(s): _meta | MCP-Protocol-Version: 2026-07-28 を付けたのに _meta が無い | params._meta に版とクライアント情報を入れる |
wrangler dev が Address already in use で落ちる | 8787 / 8788 番を別の Worker が使っている | --port と --inspector-port を変える。OAuth 版は MCP_RESOURCE のポートもそろえる |
| カスタムドメインからのリクエストが通らない | allowedHostnames の既定は localhost と workers.dev | createMcpHandler のオプションに足す7 |
セキュリティ面では、次の 3 点を守ってください。
demo-user としてトークンを得られます。本番では / で Cloudflare Access や GitHub などにサインインさせます。GitHub 経由の流れは beginUpstream() / finishUpstream() を使う手順がライブラリのドキュメントにあります/ を残していますMcpAgent です。remote-mcp-github-oauth の 2026-09-11 時点のコードは McpAgent と SDK v1 を使っていました。参考にするときは、ツール部分を createMcpHandler の形に書き換えます8createMcpHandler（ステートレス）で作る。McpAgent は機能凍結/ 1 本。MCP 2026-07-28 版のクライアントも従来のクライアントも同じルートで受けられるOAuthProvider で / を包み、OAUTH_KV と resourceMetadata.resource を設定するclaude mcp add --transport http で追加し、/ か claude mcp login で認証するwrangler deploy して MCP_RESOURCE を本番 URL にするすぐに止まるわけではありません。Cloudflare は McpAgent を機能凍結としていますが、削除の時期は発表していません1。移行ガイドには isLegacyRequest() で新旧のリクエストを振り分け、両方のルートを並行して動かす方法が載っています8。
新しく作るなら不要です。Cloudflare のドキュメントは SSE を非推奨とし、Streamable HTTP を標準としています2。Claude Code も SSE を非推奨としており、HTTP を先に試します10。
MCP のセッションを持つためには使いません。ツールが扱うアプリのデータを持つ場所としては、D1・KV・R2 と並んで今も選択肢です8。
Streamable HTTP と OAuth 2.1 に対応した MCP クライアントならつながります。ブラウザで試すなら MCP Inspector（npx @modelcontextprotocol/）に / の URL を入れます3。
筆者の wrangler dev での実行では、/ の応答の expires_in は 3600 秒でした。リフレッシュトークンも同時に発行され、Claude Code は自動で更新します10。
Agents SDK adds MCP Specification 2026-07-28 support — Cloudflare Changelog, 2026-07-27（2026-10-05 参照） ↩ ↩2 ↩3 ↩4
Build a Remote MCP server — Cloudflare Docs, 2026-07-27 更新（2026-10-05 参照） ↩ ↩2 ↩3 ↩4 ↩5
The next generation of MCP — Cloudflare Blog, 2026-08-06（2026-10-05 参照） ↩ ↩2 ↩3 ↩4
cloudflare/workers-oauth-provider — GitHub, npm 1.2.1 の README（2026-10-05 参照） ↩ ↩2 ↩3 ↩4
Google トレンド（日本・過去 90 日）・Hono の回 — Google, 2026-10-05 取得の相対値を筆者集計（2026-10-05 参照） ↩
MCP handler APIs — Cloudflare Docs, 2026-07-28 更新（2026-10-05 参照） ↩ ↩2 ↩3 ↩4
Migrate to MCP SDK v2 — Cloudflare Docs, 2026-07-28 更新（2026-10-05 参照） ↩ ↩2 ↩3 ↩4 ↩5 ↩6
Authorization — Cloudflare Docs, 2026-07-27 更新（2026-10-05 参照） ↩
Connect Claude Code to tools via MCP — Anthropic, Claude Code Docs（2026-10-05 参照） ↩ ↩2 ↩3 ↩4