Remote MCP 公開・OAuth 運用ガイド

Remote MCP server を公開運用へ持っていく場合、まず stdio と HTTP で tool/handler 定義を共通化し、Streamable HTTP endpoint と health check を用意する。次に OAuth protected resource metadata、authorization server metadata、Dynamic Client Registration、PKCE、scope、bearer token forwarding を整える。最後に Claude や ChatGPT など実クライアントで read/write tool を確認し、クライアント固有の redirect_uri、CSP、consent UI、確認 UI の差分を潰すと手戻りが少ない。

For an OAuth-protected Streamable HTTP MCP server, unauthenticated MCP endpoint requests should return HTTP 401 with a WWW-Authenticate: Bearer challenge that includes resource_metadata="<server>/.well-known/oauth-protected-resource[/mcp]" and the required scope. The server should also publish protected resource metadata containing the MCP resource URL, authorization_servers, scopes_supported, and supported bearer methods. This lets MCP clients discover the OAuth authorization server before retrying with a bearer token.

OAuth で保護した remote MCP server を汎用 MCP クライアントから接続する場合、クライアントが事前登録済み client_id を持たず、authorization server metadata の registration_endpoint を使って Dynamic Client Registration を試すことがある。MCP 側の疎通確認では、authorize/token だけでなく /.well-known/oauth-authorization-server の registration_endpoint、public client 登録、redirect_uris、scope、client metadata の検証まで含めると、実クライアント接続時の不整合を早期に見つけられる。

TypeScriptのMCPサーバーでstdioに加えてStreamable HTTPなど複数のTransportを扱う場合、tool/handler登録を含むServer生成処理をfactory関数に切り出し、stdio/httpの入口は各Transportへの接続だけを担当させる。これにより既存ツール定義を共通利用でき、Transportごとの起動・テスト・設定差分を小さく保てる。

TypeScript の MCP Streamable HTTP 入口を追加したときは、Node のローカル HTTP サーバーを一時ポートで起動し、@modelcontextprotocol/sdk の StreamableHTTPClientTransport と Client から connect して listTools などを実行すると、エンドポイント、transport 接続、tool 登録の共有をまとめて検証できる。サンドボックス環境ではローカルポート bind が制限される場合があるため、その場合は権限付き実行や CI 環境で確認する。

Remote MCP server はホスト側で動作するため、ユーザー端末の session log、cache、pending queue などにアクセスできない。MCP サーバーが remote と local の両方を提供する場合、remote の tools/list には API-backed なツールだけを出し、ローカルファイル依存ツールは local CLI/stdio mode に限定すると、クライアントが実行不能なツールを選ぶことを避けられる。

CLI MCP で API key 設定を廃止する場合は、ローカル実行向けに OAuth 2.1 の Authorization Code + PKCE を使う login / logout コマンドを用意し、refresh token をローカルに保存して access token を更新する設計が扱いやすい。token 保存先はユーザー専用ディレクトリを 0700、token ファイルを 0600 にして、logout では可能ならサーバー側 revoke とローカル削除を行う。remote MCP と local CLI MCP を併用する場合、remote 側はサーバーで完結するツールだけを公開し、ローカル cache/session 依存ツールは CLI 側に限定すると責務が分かれる。

Remote MCP server をホスティング環境へ deploy した後は、HTTP health check だけでは MCP と OAuth の実動作を保証できない。unauthenticated request の WWW-Authenticate、protected resource metadata、OAuth login/consent、tools/list、代表的な read tool、test-safe な write tool、作成データの読み戻しまでを確認すると、transport、認証、tool registration、API forwarding の問題をまとめて検出できる。

Remote MCP connector を Directory 提出する前には、Privacy Policy、usage examples、tool list/use cases、write/destructive tool の確認方針、OAuth metadata、scopes、callback/redirect_uri handling、data-only か UI widget ありかを公開ドキュメントとして整理する。Claude や ChatGPT などクライアント別の検証結果は、pending/verified の状態が分かる checklist として別セクションに残すと、提出フォーム入力や後日の再検証に使いやすい。

PaPut MCP の remote Streamable HTTP + OAuth を Claude Desktop で検証した。

結果:

• MCP endpoint は https://mcp.paput.io。/mcp は使わない。
• mcp-remote@latest 経由で Claude Desktop から接続できた。
• PaPut OAuth discovery、login / consent、token exchange、bearer token 付き MCP tool 実行まで成功。
• Claude Desktop 上で PaPut のメモ取得も成功。

一時的な Claude Desktop 設定:

{
  "mcpServers": {
    "paput": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.paput.io",
        "3334",
        "--transport",
        "http-only",
        "--static-oauth-client-info",
        "{\"client_id\":\"paput-mcp\"}",
        "--static-oauth-client-metadata",
        "{\"scope\":\"paput.read paput.write\"}"
      ]
    }
  }
}

追加した callback URI:

• http://localhost:3334/oauth/callback

判断:

• この static client 設定は検証用としては有効だが、設定が複雑で一般利用や Directory 提出向きではない。
• ChatGPT Developer Mode は同種の OAuth discovery / callback flow と仮定し、一旦 skip。
• 次は paput-api 側に OAuth Dynamic Client Registration を実装し、mcp-remote の通常設定だけで接続できる状態を目指す。

Remote MCPサーバーの審査対応では、tools/listに返す各toolへ人間向けのtop-level titleとannotations.titleを付け、readOnlyHint/destructiveHintなどの安全性annotationと一緒に検証する。HTTP endpointではOriginヘッダーが存在する場合だけ正規化したoriginを許可リストと完全一致で検証し、Originがないserver-to-server要求は許可する設計にすると、ブラウザ由来の不正originを拒否しつつMCPクライアント互換性を保ちやすい。許可originは組み込みの主要クライアントoriginに加え、環境変数で追加できるようにすると審査や新クライアント対応が容易になる。

Claude / ChatGPT へMCPコネクタを公開申請する前は、公開HTTPSエンドポイント、Streamable HTTPまたはSSE対応、OAuth metadataと認可フロー、動的クライアント登録または申請用OAuth設定、readOnlyHint/destructiveHintなどのtool annotations、公開ドキュメント、プライバシーポリシー、ロゴやスクリーンショット、審査用テストアカウント、代表的な読み取り/書き込みテストケースを揃える。ChatGPTではDeveloper Modeの私用公開とApps Directoryの公開申請が別導線であり、公開申請にはOpenAI Platformの本人/組織確認とapp権限が必要。OAuth利用時はrefresh tokenやoffline/継続アクセスの扱いも事前確認する。

Remote MCP server で「どの workspace / project / repository を対象にするか」を指定する場合、URL path、query parameter、tool input はそれぞれ向いている用途が違う。

判断基準

• 対象が外部から見ても自然なリソース識別子で、接続そのものをその対象に固定したい場合は path が向く。例として、owner と repository のように URL 階層として自然な識別子は endpoint path に載せやすい。
• 対象指定が接続オプションの一つで、dashboard や setup UI が接続 URL を生成する前提なら query parameter も有効。project scope、read-only mode、feature group のように複数オプションを組み合わせる場合は query のほうが意味が明確になる。
• 対象を毎回変えたい、または AI が一覧取得から候補を選ぶ必要がある場合は tool input と finder/list tool が向く。曖昧な検索結果を勝手に先頭採用せず、候補を返してユーザー確認に回す。

注意点

ユーザー単位の alias は URL だけでは一意にならないため、OAuth 後の user と alias の組で解決する。query parameter は token を入れる場所ではないが、非秘密の scope option としては実サービスでも使われている。path/query のどちらでも、フロント側で設定 URL を生成し、クライアントがその URL を保持することを確認する。

MCP サーバーでローカルファイル由来の取り込み機能を設計するとき、AI クライアント自身がそのファイルを読めるなら、サーバー側にローカルファイル読み取り tool を持たせず、skill や手順書でクライアントに読ませる選択肢を優先する。

判断基準

• サーバーの責務は、処理済み状態の取得、候補や成果物の登録、ポリシー更新など、API-backed な状態管理に寄せる。
• ローカルファイルの探索、必要部分の抜粋、ユーザー確認は、ローカルファイルアクセス権を持つ AI クライアント側の手順にする。
• Remote と local の両方の接続形態を提供する場合、接続形態ごとにツールセットや保存場所を分けず、永続状態は共通 API に集約する。
• 読み取り対象が端末上のログや transcript なら、MCP サーバーが読む tool を残すより、クライアントの明示的なファイルアクセスとユーザーへの報告に寄せた方が権限境界が明確になる。

避けるべき設計

• local CLI mode にだけファイル読み取り tool を残し、remote mode と説明・挙動が分岐する設計。
• local cache と remote API storage を同期する設計。状態分岐や競合を増やし、ユーザーに cache の存在を意識させやすい。
• 互換性のために古い cache/status tool を残す設計。運用の正本が曖昧になる。

検証観点

実装後は tools/list、skill、rules、docs を横断検索し、サーバーがローカルファイルを読む前提の文言や tool が残っていないことを確認する。あわせて、未処理判定と処理済み登録が API-backed な tool で完結することをテストする。

SaaS 型 MCP server で Remote HTTP と MCP client OAuth flow が使え、ローカルファイル読み取りや local cache の独自価値がなくなった場合、互換用として stdio server や CLI OAuth login を残さず、Remote HTTP に接続方式を一本化する判断が有効。

判断基準

• ユーザーごとの認可を hosted service 側の OAuth flow で完結できる。
• local CLI が単なる API proxy になっており、ローカルでしかできない処理がない。
• project や workspace の文脈を URL scope や tool input で指定でき、環境変数の fuzzy match に依存しない。
• docs、front、skills、rules、tools の説明が Local と Remote で分岐し、ユーザーに token file や stdio 設定を説明するコストが残っている。

残すもの

Local CLI を MCP 接続方式として廃止しても、skill や rule を配置する setup utility や skill export utility は残せる。これは MCP transport ではなく、AI client の作業手順を配布するためのローカル補助機能として扱う。

検証観点

実装後は server entrypoint、CLI help、package scripts、API client auth fallback、docs、front text、tool descriptions を横断検索し、stdio、local OAuth、環境変数 project match、local cache を前提にした文言や code path が残っていないことを確認する。

機能・モード・一部ツールを破壊的に削除したあと、公開や外部ディレクトリ/ストアへの提出直前に行うドキュメント最終チェックは、利用者向けの公開ドキュメントだけを見ると不十分になりやすい。古い前提の記述は、検査者が見落としやすい場所に残る。

どこに古い記述が残るか

• 配布物（パッケージ同梱物）に含まれない内部の開発者向けドキュメント（貢献者ガイドや AI 向け指示ファイル等）。同梱対象から外れていても公開リポジトリ上には残り、審査者が閲覧しうる。
• 開発用の設定ファイル（ローカル接続定義など）。削除した起動方式や廃止した環境変数を指したまま壊れていることがある。
• メタデータ（バージョン、エントリポイント、起動スクリプト）とその説明文の食い違い。 公開ドキュメント本体は普通に確認されるので、むしろ上記の周辺ファイルを明示的に対象に含めるのが要点。

審査フォームがVCSブランチを指す場合の落とし穴

提出フォームに記載するドキュメントURLが、リポジトリの特定ブランチ（main 等）の生ファイルを指していることがある。この場合、ローカルの作業ツリーで修正済みでもコミット・push していなければ、審査者はそのURLで古い内容を見る。よって公開ドキュメントの修正をコミットして提出先ブランチへ反映することが、提出を実際に通すための前提工程になる。「修正済み」と「反映済み」を混同しない。

バージョンとタグの整合

機能やツールの削除は後方非互換なので、セマンティックバージョニングでは原則 MAJOR を上げる（新規追加だけなら MINOR）。さらに、すでに発行済みのタグや公開済みのパッケージバージョンは再利用できないため、据え置きのままだと公開・タグ付けが失敗する。提出前にバージョンを上げ、提出物の正本（公開版）とドキュメント内容を一致させる。

検証観点

削除した方式に固有のキーワード（廃止コマンド名、削除ツール名、廃止した環境変数、旧トランスポート名）を、公開docs・内部docs・設定ファイル・スクリプト説明まで横断検索して残存ゼロを確認する。提出フォームに載せる各URLを実際に開いて最新内容が返ることを確認する。実際に登録される機能一覧（ツール一覧など）とドキュメントの一覧を機械的に突き合わせ、過不足が無いか確認する。