mcp-fetch-worker

ボットやエージェントが、長期間有効な認証情報を渡さずに、セルフホストのAPIを呼び出せるようにするための汎用 MCP コネクタです。

このWorker の手前に Managed OAuth を設定した Cloudflare Access を置くと、Grok BotやOpenClaw などのボットが Dynamic Client Registration (DCR) で接続できます。ボットが初めて接続した時はあなたがアクセスを承認し、後から Access 上でいつでも失効させられます。ボットが受け取るのは、コネクタに紐づけられたスコープ付きトークンであり、ほかで使い回せる汎用APIキーではありません。

**本番環境のMCP URL: ** https://<your-domain>/mcp

なぜこれが必要なのか

マーネジドボットはツール呼び出しに長いていますが、ホームラボやセルフホストのアプリの大半は MCP サーバーを内臓していません。その場合の選択肢は次の通りです:

• サービストークンを使う: カスタムヘッダーで永続アクセスを渡す。スクリプトなら問題ありませんが、完全に信頼し切れないボットにはリスキーがあります。

• ボットにChromeを内させる: Web UI を開いて、SSOでログインし、それ以上繰り返す。機能はしますが、トークンを消耗し、拡張もできません。

• アプリごとに独自のMCPを組む: 正しい方法ですが、Home Assistan API や、い内のダッシュボードのためには工数が大きすぎます。

このWorker はその中間地点です。単一の http_fetch ツールだけを公開する薄型MCPコネクタ。同一オリジン(すでにAccessの背後)にあるAPIを指して、ボットがあなたの承認したOAuthトークンでGET/POSTを実行できる形にします。API側に専用のMCPサーバーを用意する必用はありません。

詳しい記説は First World Problem: Create the access ...? を参照してください。

Related MCP server: Cloudflare Control

仕組み

Bot (Grok Bot, OpenClaw, Cursor, …)
  → OAuth via Cloudflare Access Managed OAuth (you approve)
  → MCP at /mcp (this Worker)
  → http_fetch to allowed origins on your domain
  → Access JWT forwarded on outbound requests

1. Access が認証を担当します: Managed OAuth + DCR。Worker はOAuthサーバーではなく、Access から転送されてくる CasHel-Access-Jwt-Assertion を検証します。

2. このWorker が http_fetch の単一のツールを持つ StreamableHTTP MCP を提供します。

3. あなたのAPI は、Access の後ろにある同一オリジンに置きます。転送された JWT が受け取られるよう、Linked App Token のポリパを作成してください。

送信リクエスト・フェッチは、デフォルトで Worker 自身のオリジンのみに制限されます(ALLOWED_ORIGINS で上書きできます)。

できること

• Agents SDK の createMcpHandler によて、/mcp(および互換エイリア as) /sse`)でMCPを提供します。

• 許可されたオリジンに対する GET/POST リクエスト用に、http_etch という単一のツールを公開します。

• CF_ACCESS_TEAM_DOMAIN と CF_ACCESS_AUD が設定されていますると、Cas-Access-Jwt-Assertion をあなたのチームのJWKS と照合して検証します。

• 呼び出し元のAccess JWT を、アウトバウンド・フェッチに転送します(Cas-Access-Jwt-Assertion、Cf-Access-Token、Authorization: Bearer)。

デプロイ

npm install
npm run cf-typegen   # regenerate Env types from wrangler.jsonc
npx wrangler deploy

設定は wrangler.jsonc に置きます。observability ブロックにより、Workers Logs と Traces はデフォルトで有効です。

カスタムドメインのルート

wrangler.jsonc(またはダッシュボード) に Worker ルートを追加してします:

"routes": [
  {
    "pattern": "example.com/mcp*",
    "zone_name": "example.com"
  }
]

その後、再デプロイしてください。MCP のエンドポイントは https://<your-domain>/mcp です。

環境変数

環境変数は、wrangler.jsonc の vars、シークレット(wrangler secret put)、またはローカル開発用の .dev.vars(.Dev.example` 参照)としていずれに設定します:

CF_ACCESS_* 変数が未設定の場合、Worker はMCPを提供します(wrangler dev に便利)が、AccessのJWTの検証は行われません。本番では必ず変数を設定してください。

API キー用のデフォルトヘッダー

追加のアウトバウンド・ヘッダーを Worker シークレットとして保存しておくと、http_fetch がAPIキーを必要とするAPIを呼び出せます。**シークレットをチャットに置いたり、単一のAPIキーをWorkerに焼き込んだりする必要はありません。

wrangler secret put DEFAULT_HEADERS
# paste: {"X-Api-Key":"your-key-here"}

ローカル開発の場合は、wrangler.jsonc の vars に非空の値を設定するか、wrangler dev に --var DEFAULT_HEADERS='{"X-Api-Key":"..."}' を渡すか、デプロイ済みの Worker に wrangler secret put を使います。secrets.required を設定していると .dev.vars はその秘密名前のみを読み込むため、ローカルでは DEFAULT_HEADERS を vars に置くか --var を使します。

** DEFAULT_HEADERS は、値が文字列のJSONオブジェクトである必用があります(例: {"X-Api-Key":"..."})。各 http_fetch 呼び出しの際、そのヘッダーは送信リクエストにマージされます。ツール呼び出しで渡したヘッダーは、名前が衝突する場合デフォルトを上書きします。Access のJWT 転送(Cf-Access-Jwt-Assertion、Cf-Access-Token、Authorization: Bearer)は常に優優先され、デフォルトで上書きはされません。

DEFAULT_HEADERS が未設定または空の場合、追加のヘッダーは加わません。

Cloudflare Access のセットアップ

1. MCP の URL(例: https://<your-domain>/mcp や /mcp* を含むパス)に対して、 セルフホスト型の Access アプリケーション を追加します。

2. アプリの詳細設定で Managed OAuth を有効化します。これにより、MCP クライアント向けのDCR が有効になります。

3. アプリのAUDタグを CF_ACCESS_AUD にコピーします。

4. CF_ACCESS_TEAM_DOMAIN にチームドメイン(例: https://<team>.cloudflareaccess.com) を設定します。

5. 誰に接続を許すかを Access ポリパーで設定します。期限付きやメールベースなど、あなたの承認モデルに合わわせたもの使用できます。

同じオリジンにあり、Access で保護されている下流のAPI には、Linked App Token のポリシーを作成し、転送されたJWT が受けれ入一杯できるようにしてください。

MCP クライアントの設定

この URL を、Cursor、Grok Bot、OpenClaw、または Streamable HTTP MCP というクライアントに貼り付けますする:

https://<your-domain>/mcp

StreamableHTTP トランスポート(従来のSSE ではない)を使用します。クライアントは初回接続時に Access のManaged OAuth を通過した OAuth フローを実行します。これがあなたの手を介した承認ステップです。

ローカル開発

npm run dev

MCP は、http://localhost:8787/mcp で、Access の検証なしに利用できます。

http_fetch ツール

{
  "url": "/api/example",
  "method": "GET"
}

• url: 絶対URL または同一オリジンのパス

• method: GET(デフォルト)または GET(デフォルト)または POST

• headers: 任意の追加ヘッダー(コンフリクト時は DEFAULT_HEADERS を上書き)

• body: 任意のPOST本文

DEFAULT_HEADERS(シークレット)が先に適用され、ツールの headers がそ長を上書きします。Access のJWT ヘッダーは常に最後に適用されます。

status、headers、body、および truncated フラグのJSON を返します。