remote MCP サーバーが401を返すときは、tokenを作り直す前に、どのendpointで誰が401を返したかを確認します。MCP endpoint、認証metadata、authorization サーバーのtoken endpoint、上流APIは別の境界です。別resource向けtokenを流用したり、audience検証を外したりして通す処置にはしません。
本稿はHTTP transportのMCP認可診断です。stdioのstdoutや環境変数による起動とは分けます。サーバー接続、token取得・解析、再同意、permission変更、tool実行は実施していません。例のURLやscopeは架空で、製品の接続成功を示しません。
目次
失敗した要求と認可段階を固定する
host/client、サーバー URL、transport、対応protocol バージョン、要求時刻、HTTPステータス、error種別を記録します。reverse proxyやlogin画面の401が、MCP サーバーからのchallengeとして透過されているかも確認します。responseのbodyがHTMLなのか、想定するmetadata/認可errorなのかを見ます。
表は横にスクロールできます
| 401が出る場所 | 最初の確認 | 同じにしない問題 |
|---|---|---|
| MCP endpointの初回 | 認可要求とmetadata発見 | toolの業務失敗 |
| metadata取得 | URL・公開条件・応答形式 | access token期限だけ |
| token endpoint | client・code・PKCE等 | resourceのaudienceだけ |
| token付きMCP要求 | 発行元・対象resource・期限 | stdioのJSON破損 |
| tool先のAPI | 上流専用の接続 | MCP tokenの丸ごと転送 |
Authorizationやtoken全文、code、Cookieをticketへ貼りません。JWTに見えるtokenでも外部decodeサイトへ送らず、必要なら認可実装の管理者が安全な環境で扱います。payloadを読めたことだけでは署名や有効性を検証したことになりません。
protected resource metadataと認可サーバーを照合する
MCP 2026-07-28の認可仕様（新しいタブで開く）に沿って、401のWWW-Authenticateとresource_metadataなど、利用clientが対応する発見経路を確認します。MCP サーバーとauthorization サーバーが同じhostとは限りません。URLから勝手にtoken endpointを組み立てず、検証したmetadataとの対応を見ます。
metadataへのredirect、proxyのheader削除、誤ったJSONやcontent typeがないかも確認します。endpoint直下にmetadataを置いたつもりでも、path prefixや別hostへの移設でclientが異なる場所を見ている場合があります。metadataを発見できた段階と、信頼できるissuerを確認した段階を分けます。
clientとサーバーが別バージョンを想定する場合、現行仕様の一部分だけを貼り足しません。実装のSDK/versionと、その認可方式が対応するspecを固定して読みます。旧版のガイドで接続できたことを、現在の全hostでの互換性保証にはしないようにします。
issuer・resource・audience・scopeを別々に確認する
tokenを発行したissuer、clientが要求したresource、サーバーが期待するaudience、許可scopeを対応表にします。OAuthログインのID tokenと、MCP resource向けaccess tokenを混同しません。同じ利用者や同じ認可providerでも、別API向けtokenが対象MCPへ有効とは限りません。
表は横にスクロールできます
| 条件 | 比較するもの | 解決にならない操作 |
|---|---|---|
| 発行元 | 選択したissuerと検証設定 | 似たhostなら信用 |
| 対象resource | 認可要求とMCPの正式URI | scopeだけ追加 |
| audience | tokenの対象とサーバー | 検証を無効化 |
| 期限・状態 | 有効期間と失効条件 | 同じtokenの無限再送 |
| scope | 必要operationとchallenge | 全scopeの一括要求 |
公式仕様は、サーバーが自身向けに発行されたaccess tokenを検証することを求めています。audienceが違うなら、検証条件を緩めるより、正しいresourceへ正しい経路でtokenが発行される設定を確認します。MCPへ届いたtokenを、そのまま上流の別APIへ渡す設計にも進みません。
401と403、追加scopeの要求を分ける
現行仕様は、認可が必要・token無効の401と、scopeや権限不足の403を区別します。実装やproxyの挙動も見ながら、状態だけでなくchallengeとerrorを読みます。403が出るたびに再ログインする前に、失敗operationへ必要なscopeやresource側の権限を特定します。
追加認可が必要な設計なら、必要なscopeと既存の許可をどう扱うかをclient側で確認します。利用者へ権限を広げる理由を示し、同じresource・operationで再認可を繰り返さない回数制限を設けます。認可を取り直すこと自体を修復成功と扱わず、元の要求が何をしたかまで確認します。
最小の読取から再確認し、書込の不明状態を残す
変更前のサーバー URL、metadata対応、client設定、認証経路を秘密値なしで保存します。許可された検証では、metadata、認可、token付きの接続、一覧、最小の読取を段階ごとに確認します。認証できても、誤ったtenantやaccountへ接続した場合は合格にしません。
書込toolの要求後に401等へ見えた場合も、下流で何も実行されていないとは決めつけません。対象IDと状態を読み戻し、完了・失敗・不明を分けてから再試行します。今回の設定差分を戻しても既存の認可や外部更新が残る場合があるため、運用上の整理は別に扱います。
完了記録には、401を返した層、確認したprotocolとissuer/resourceの関係、変更した最小範囲、回復した操作、未確認のscope・書込経路を残します。tokenの値を記録せず、次の担当が同じ境界から診断できる状態にします。