Remote MCP サーバーを構築する

このガイドでは、Streamable HTTP トランスポートを使って Cloudflare 上にリモート MCP サーバーをデプロイする方法を示します。選択肢は 2 つです。

認証なし — 誰でも接続してサーバーを使えます（ログイン不要）。
認証と認可あり — ユーザーはツール利用前にサインインします。ユーザーの権限に応じて、エージェントが呼べるツールを制御できます。

アプローチの選び方

Agents SDK は MCP サーバーの作成方法を複数提供します。用途に合うアプローチを選びます。

アプローチ	状態を持つか	プロトコルパス	向いている用途
`createMcpHandler()`	いいえ	レガシー互換のあるステートレス	新しいステートレスツール
`createLegacyMcpHandler()`	任意	レガシー	既存の一時的な `WorkerTransport` ルート
`McpAgent`	はい	レガシー	非推奨の Durable Object と RPC サーバー
Raw SDK トランスポート	トランスポート次第	SDK パッケージ次第	トランスポートを自前で持つ場合

新しいステートレスサーバーには createMcpHandler を使います。レガシーな状態依存がない既存の McpAgent は、直接移行できます。MCP セッション状態、RPC、プッシュリクエスト、ストリーム、リプレイを使う場合は、ステートレスな同等機能を計画し、移行中はステートレスレーンとレガシーレーンの両方を提供します。段階的なロールアウトは MCP SDK v2 への移行を参照してください。

最初の MCP サーバーをデプロイする

まず認証なしの公開 MCP サーバー ↗ をデプロイし、あとからユーザー認証とスコープ付き認可を追加できます。サーバーに認証が必要だとすでに分かっている場合は、次のセクションへ進んでください。

ダッシュボードから

次のボタンは、サンプル MCP サーバー ↗ を Cloudflare アカウントへデプロイするために必要な手順を案内します。

デプロイ後、このサーバーは workers.dev サブドメインで稼働します（例: remote-mcp-server-authless.your-account.workers.dev/mcp）。すぐに AI Playground ↗（リモート MCP クライアント）、MCP inspector ↗、またはその他の MCP クライアントで接続できます。

GitHub または GitLab アカウント上に、MCP サーバー用の新しい git リポジトリが作成されます。リポジトリの main ブランチへ変更をプッシュするかプルリクエストをマージするたびに、Cloudflare へ自動デプロイされます。このリポジトリをクローンし、ローカルで開発し、独自のツールで MCP サーバーをカスタマイズできます。

CLI から

Wrangler CLI を使い、ローカルマシン上に新しい MCP サーバーを作成して Cloudflare へデプロイできます。

ターミナルを開き、次のコマンドを実行します。
npm create cloudflare@latest -- remote-mcp-server-authless --template=cloudflare/ai/demos/remote-mcp-authless
yarn create cloudflare remote-mcp-server-authless --template=cloudflare/ai/demos/remote-mcp-authless
pnpm create cloudflare@latest remote-mcp-server-authless --template=cloudflare/ai/demos/remote-mcp-authless
セットアップ中は、次のオプションを選びます。 - Do you want to add an AGENTS.md file to help AI coding tools understand Cloudflare APIs? には No を選びます。 - Do you want to use git for version control? には No を選びます。 - Do you want to deploy your application? には No を選びます（デプロイ前にサーバーをテストします）。

これで依存関係がインストールされた MCP サーバーのセットアップが完了します。
プロジェクトフォルダーへ移動します。
```
cd remote-mcp-server-authless
```
新しいプロジェクトのディレクトリで、次のコマンドを実行して開発サーバーを起動します。
```
npm start
```
```
⎔ Starting local server...
[wrangler:info] Ready on http://localhost:8788
```
ローカルポートはコマンド出力で確認します。この例では MCP サーバーはポート 8788 で動き、MCP エンドポイント URL は http://localhost:8788/mcp です。

Note
ウェブブラウザーで /mcp URL を直接開いても、MCP サーバーとはやり取りできません。/mcp エンドポイントは MCP クライアントからの MCP プロトコルメッセージを期待します。ブラウザーはデフォルトではそれを送りません。次のステップで、MCP クライアントからサーバーへ接続する方法を示します。
サーバーをローカルでテストします。
1. 新しいターミナルで MCP inspector ↗ を実行します。MCP inspector は対話型の MCP クライアントで、ウェブブラウザーから MCP サーバーへ接続し、ツールを呼び出せます。
```
npx @modelcontextprotocol/inspector@latest
```
```
🚀 MCP Inspector is up and running at:
	http://localhost:5173/?MCP_PROXY_AUTH_TOKEN=46ab..cd3

🌐 Opening browser...
```
  MCP Inspector はウェブブラウザーで起動します。ブラウザーを開き、http://localhost:<PORT> へ移動して手動起動することもできます。MCP Inspector が動いているローカルポートはコマンド出力で確認します。この例では、MCP Inspector はポート 5173 で提供されます。
2. MCP inspector で MCP サーバーの URL（http://localhost:8788/mcp）を入力し、Connect を選びます。List Tools を選ぶと、MCP サーバーが公開するツールが表示されます。
MCP サーバーを Cloudflare へデプロイできます。プロジェクトディレクトリから次を実行します。
```
npx wrangler@latest deploy
```
MCP サーバーを持つ Worker にすでに git リポジトリを接続している場合は、リポジトリの main ブランチへ変更をプッシュするかプルリクエストをマージしてデプロイできます。

MCP サーバーは *.workers.dev サブドメインの https://remote-mcp-server-authless.your-account.workers.dev/mcp にデプロイされます。
リモート MCP サーバーをテストするには、デプロイ済み MCP サーバーの URL（https://remote-mcp-server-authless.your-account.workers.dev/mcp）を、http://localhost:5173 で動いている MCP inspector に入力します。

これで、MCP クライアントが接続できるリモート MCP サーバーができました。

ローカルプロキシ経由で MCP クライアントから接続する

リモート MCP サーバーが動いたら、mcp-remote ローカルプロキシ ↗ を使い、Claude Desktop や他の MCP クライアントから接続できます。クライアント側がリモートトランスポートや認可をサポートしていなくても使えます。実際の MCP クライアントで、リモート MCP サーバーとのやり取りを試せます。

たとえば、Claude Desktop から接続するには次を行います。

Claude Desktop の設定を、MCP サーバーの URL を指すように更新します。

{
	"mcpServers": {
		"math": {
			"command": "npx",
			"args": [
				"mcp-remote",
				"https://remote-mcp-server-authless.your-account.workers.dev/mcp"
			]
		}
	}
}

MCP サーバーを読み込むため、Claude Desktop を再起動します。完了すると、Claude はリモート MCP サーバーを呼び出せます。
テストとして、Claude にいずれかのツールを使うよう依頼します。例:
```
Could you use the math tool to add 23 and 19?
```
Claude はツールを呼び出し、リモート MCP サーバーが生成した結果を表示します。

他の MCP クライアントでリモート MCP サーバーを使う方法は、リモート MCP サーバーをテストするを参照してください。

認証を追加する

先にデプロイした公開 MCP サーバーの例では、どのクライアントもログインなしで接続し、ツールを呼び出せます。MCP サーバーにユーザー認証を追加するには、OAuth プロバイダーとして Cloudflare Access またはサードパーティサービスを統合します。MCP サーバーは安全なログインフローを扱い、MCP クライアントが認証済みツール呼び出しに使えるアクセストークンを発行します。ユーザーは OAuth プロバイダーでサインインし、スコープ付き権限で、MCP サーバーが公開するツールと AI エージェントがやり取りすることを許可します。

Cloudflare Access OAuth

MCP サーバーを、Cloudflare Access によるユーザー認証必須に設定できます。Cloudflare Access は ID の集約役として動き、ユーザーのメール、既存の ID プロバイダー（GitHub や Google など）からのシグナル、IP アドレスやデバイス証明書などの属性を検証します。ユーザーが MCP サーバーに接続すると、設定した ID プロバイダーへのログインを求められ、Access ポリシーを通過した場合にだけアクセスが許可されます。

手順付きのデプロイガイドは、Access for SaaS で MCP サーバーを保護するを参照してください。

サードパーティ OAuth

OAuth 2.0 仕様をサポートする任意の OAuth プロバイダーに MCP サーバーを接続できます。GitHub、Google、Slack、Stytch、Auth0、WorkOS などです。

次の例は、GitHub を OAuth プロバイダーとして使う方法です。

ステップ 1 — 新しい MCP サーバーを作成する

次のコマンドを実行し、GitHub OAuth 付きの新しい MCP サーバーを作成します。

npm create cloudflare@latest -- my-mcp-server-github-auth --template=cloudflare/ai/demos/remote-mcp-github-oauth

yarn create cloudflare my-mcp-server-github-auth --template=cloudflare/ai/demos/remote-mcp-github-oauth

pnpm create cloudflare@latest my-mcp-server-github-auth --template=cloudflare/ai/demos/remote-mcp-github-oauth

依存関係がインストールされた MCP サーバーのセットアップが完了します。そのプロジェクトフォルダーへ移動します。

cd my-mcp-server-github-auth

サンプル MCP サーバーの src/index.ts を開くと、主な違いは defaultHandler が GitHubHandler になっていることです。

import GitHubHandler from "./github-handler";

export default new OAuthProvider({
	apiRoute: "/mcp",
	apiHandler: MyMCP.serve("/mcp"),
	defaultHandler: GitHubHandler,
	authorizeEndpoint: "/authorize",
	tokenEndpoint: "/token",
	clientRegistrationEndpoint: "/register",
});

これにより、ユーザーは認証のため GitHub へリダイレクトされます。ただし動作させるには、次のステップで OAuth クライアントアプリを作成する必要があります。

ステップ 2 — OAuth App を作成する

GitHub を MCP サーバーの認証プロバイダーとして使うには、GitHub OAuth Apps ↗ を 2 つ作成します。1 つはローカル開発用、もう 1 つは本番用です。

ステップ 2.1 — ローカル開発用の新しい OAuth App を作成する

github.com/settings/developers ↗ を開き、次の設定で新しい OAuth App を作成します。
- Application name: My MCP Server (local)
- Homepage URL: http://localhost:8788
- Authorization callback URL: http://localhost:8788/callback
作成した OAuth アプリのクライアント ID を GITHUB_CLIENT_ID として追加し、クライアントシークレットを生成して GITHUB_CLIENT_SECRET としてプロジェクトルートの .env ファイルに追加します。これはローカル開発でシークレットを設定するために使います。
```
touch .env
echo 'GITHUB_CLIENT_ID="your-client-id"' >> .env
echo 'GITHUB_CLIENT_SECRET="your-client-secret"' >> .env
cat .env
```
次のコマンドを実行して開発サーバーを起動します。
```
npm start
```
MCP サーバーは http://localhost:8788/mcp で動きます。
新しいターミナルで MCP inspector ↗ を実行します。MCP inspector は対話型の MCP クライアントで、ウェブブラウザーから MCP サーバーへ接続し、ツールを呼び出せます。
```
npx @modelcontextprotocol/inspector@latest
```
ウェブブラウザーで MCP inspector を開きます。
```
open http://localhost:5173
```
inspector に MCP サーバーの URL http://localhost:8788/mcp を入力します。
右側のメインパネルで OAuth Settings ボタンをクリックし、Quick OAuth Flow をクリックします。

GitHub のログインまたは認可ページへリダイレクトされます。MCP Client（inspector）に GitHub アカウントへのアクセスを許可したあと、inspector へ戻ります。
サイドバーの Connect をクリックすると、「List Tools」ボタンが表示されます。これを使うと、MCP サーバーが公開するツールが一覧されます。

ステップ 2.2 — 本番用の新しい OAuth App を作成する

本番用の新しい OAuth App を作成するには、ステップ 2.1 を繰り返します。

github.com/settings/developers ↗ を開き、次の設定で新しい OAuth App を作成します。

Application name: My MCP Server (production)
Homepage URL: デプロイ済み MCP サーバーの workers.dev URL を入力します（例: worker-name.account-name.workers.dev）
Authorization callback URL: デプロイ済み MCP サーバーの workers.dev URL の /callback パスを入力します（例: worker-name.account-name.workers.dev/callback）

作成した OAuth アプリのクライアント ID とクライアントシークレットを、Wrangler CLI で追加します。

npx wrangler secret put GITHUB_CLIENT_ID

npx wrangler secret put GITHUB_CLIENT_SECRET

npx wrangler secret put COOKIE_ENCRYPTION_KEY

COOKIE_ENCRYPTION_KEY には任意のランダム文字列を使います。たとえば openssl rand -hex 32 の出力です。

KV 名前空間をセットアップします。

a. KV 名前空間を作成します。

npx wrangler kv namespace create "OAUTH_KV"

b. 得られた KV ID で wrangler.jsonc ファイルを更新します。

{
	"kvNamespaces": [
		{
			"binding": "OAUTH_KV",
			"id": "<YOUR_KV_NAMESPACE_ID>"
		}
	]
}

MCP サーバーを Cloudflare の workers.dev ドメインへデプロイします。
```
npm run deploy
```
AI Playground ↗、MCP Inspector、またはその他の MCP クライアントを使い、worker-name.account-name.workers.dev/mcp で動いているサーバーへ接続し、GitHub で認証します。