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 の通常設定だけで接続できる状態を目指す。