api-gateway-mcp

Claude Cowork や ChatGPT から、既存のコネクタではできない API 呼び出しを行うための、汎用 API ゲートウェイです。Cloudflare Workers で動くリモート MCP サーバーとして、顧客ごとにデプロイします。

• MCP: OAuth でログインしたユーザーに、寿命の短いゲートウェイトークンを発行します。

• REST: /api/<service>/<path> をトークンで受け付け、上流のサービスに認証情報を注入して中継します。ボディは素通しです。

• Web 画面: ユーザーが連携先の認証情報を登録します。

設計は docs/concept.md と docs/auth-design.md を参照してください。

使い方(クライアント側)

1. コネクタを追加します。ゲートウェイの Web 画面(https://<ゲートウェイ>/)に、追加用のリンクがあります。

   • Pro / Max: 個人の設定でカスタムコネクタとして https://<ゲートウェイ>/mcp を追加します。

   • Team / Enterprise: Owner が組織の設定で同じ URL を追加し、各メンバーが接続します。

2. 各ユーザーは https://<ゲートウェイ>/ にサインインし、連携先の認証情報を登録します。

3. Claude は list_credentials で認証情報を確かめ、issue_token でトークンを受け取ります。

4. サンドボックス内のスクリプトは、そのトークンで REST を呼びます。

curl -H "Authorization: Bearer $TOKEN" "https://<ゲートウェイ>/api/board/v1/clients"

Related MCP server: Cloudflare Remote MCP Server

スキル(プラグイン)

このリポジトリは Claude のプラグインのマーケットプレイスを兼ねています。plugins/api-gateway に、ゲートウェイの共通手順(api-gateway)とサービス別のスキル(board など)が入っています。プラグインにはコネクタの URL を含めていないので、どのデプロイでも同じものを使えます。

• Pro / Max: Customize > Plugins > Add marketplace で novshi-tech/api-gateway-mcp を追加し、api-gateway をインストールします。

• Team / Enterprise: Owner が Organization settings > Plugins & skills で、このリポジトリ(または、これを参照する社内のマーケットプレイス用リポジトリ)を同期し、配布方法を選びます。

• zip でアップロードする場合: npm run plugin:zip で dist/api-gateway-<version>.zip を作り、Plugins の Upload plugin で追加します。更新するときは plugin.json の version を上げて作り直し、同じ名前でアップロードし直します。

2026-09 時点では、個人の Cowork で GitHub のマーケットプレイスからのインストールが同期に失敗しました(Claude Code では同じマーケットプレイスからインストールできます)。その場合は zip を使ってください。

board のエンドポイント一覧は tools/gen-board-reference.py で board の OpenAPI から生成しています。

スクリプトでは User-Agent を明示してください。Python の urllib の既定値などは、Cloudflare に Error 1010 で拒否されることがあります。

Team / Enterprise では、組織の管理者がコード実行のネットワーク設定で、ゲートウェイのドメインを許可する必要があります。

デプロイ

1. IdP にアプリを登録する

リダイレクト URI を 2 つ登録します。

• https://<ゲートウェイ>/oauth/callback(MCP クライアントの接続)

• https://<ゲートウェイ>/login/callback(Web 画面のサインイン)

Entra ID はシングルテナントのアプリとして登録し、OIDC_ISSUER を https://login.microsoftonline.com/<tenant-id>/v2.0 にします。Google は Workspace のドメインを ALLOWED_DOMAINS に必ず指定します。

2. 設定する

wrangler.example.jsonc を wrangler.jsonc にコピーし(wrangler.jsonc は git の管理外です)、vars に PUBLIC_URL、IdP の設定、SERVICES(連携先)を書きます。KV ネームスペースを作って ID を設定します。

cp wrangler.example.jsonc wrangler.jsonc
npx wrangler kv namespace create OAUTH_KV
npx wrangler secret put OIDC_CLIENT_SECRET
openssl rand -base64 32 | npx wrangler secret put SIGNING_KEY
openssl rand -base64 32 | npx wrangler secret put ENCRYPTION_KEY
npx wrangler deploy

ENCRYPTION_KEY を変えると、登録済みの認証情報は復号できなくなります。

3. OAuth の連携先(freee など)

SERVICES で auth.type を oauth2 にした連携先は、Web 画面から OAuth(認可コード + PKCE)で接続します。連携先にアプリを登録し、コールバック URL に https://<ゲートウェイ>/connect/callback を指定します。クライアント ID とシークレットは、サービス名を大文字にした名前で登録します。

npx wrangler secret put OAUTH_FREEE_CLIENT_ID
npx wrangler secret put OAUTH_FREEE_CLIENT_SECRET

Microsoft Graph は、サインイン用とは別の Entra アプリを登録します。プラットフォームは「Web」で、wrangler.example.jsonc の scope にある委任のアクセス許可を付けて、管理者の同意を与えます。

アクセストークンは期限の 1 分前からゲートウェイがリフレッシュします。リフレッシュトークンが失効したら、画面に「再接続」が出ます。

GitHub Actions でデプロイする

.github/workflows/ci.yml は、main に push するとテストのあとにデプロイします。リポジトリの Environment production に、次のシークレットを登録します。

• CLOUDFLARE_API_TOKEN: 「Edit Cloudflare Workers」テンプレートで作った API トークン

• CLOUDFLARE_ACCOUNT_ID: Cloudflare のアカウント ID

• WRANGLER_CONFIG: wrangler.jsonc の中身まるごと

Worker のシークレット(SIGNING_KEY など)は Cloudflare 側にあるので、ここには要りません。

開発

npm install
cp wrangler.example.jsonc wrangler.jsonc
cp .dev.vars.example .dev.vars   # 値を埋める
npm run dev
npm run typecheck
npm test          # Worker のテストと、スキルのスクリプトのテスト

License

MIT.