リモートMCPのOAuth認証 — 仕組みとClaude Codeでの実装変化

リモートMCPサーバーに接続するとき、Claude CodeはAPIキーではなくOAuth 2.1ベースの認可フローでアクセストークンを取得します。トークンなしでリクエストを送ると401が返り、そこから認可サーバーを見つけ、クライアントとして登録し、PKCE(Proof Key for Code Exchange、認可コード横取り対策)付きの認可コードを交換してようやくトークンにたどり着く手順です。MCPの認可仕様は2026-07-28版で改訂されました。Dynamic Client Registration(DCR)を非推奨にし、Client ID Metadata Documents(CIMD)へ主軸を移す変更です。仕様のRFCレベルの中身と、Claude Codeが2025年6月の初対応からどう実装を積み重ねてきたかをまとめます。

なぜリモートMCPにAPIキーでなくOAuthが必要なのか

MCPのトランスポートはstdioとStreamable HTTPが主流で、認可の要不要はここで分かれます。stdio接続はクライアントがサーバーをローカルの子プロセスとして起動するため、ネットワークを介さず環境変数でクレデンシャルを渡せば足ります。MCP仕様自身も、stdioトランスポートの実装には認可フローを適用しないよう求める立場です。

一方Streamable HTTPで接続するリモートサーバーは、クライアントとサーバーが初対面であることが前提です。GitHubやSentry、Slackのようなリモートサーバーは不特定多数のクライアントから接続され、あらかじめクライアントIDを交換しておく関係が成立しません。「初対面の相手にどうやって安全にトークンを渡すか」が、リモートMCPの認可仕様が解く課題です。

仕様はOAuth 2.1をベースにしています。保護リソースメタデータ(RFC9728)・認可サーバーメタデータ(RFC8414)・PKCE・Resource Indicators(RFC8707)を組み合わせた答えです。Claude.ai・Claude Desktop・Claude Codeの3面での対応表はMCPとはにまとめてあります。本記事はそのうち、リモートサーバーとのOAuth認可フローの仕組み自体に絞ります。

認可フローの全体像 — 401から取得までの7段階

リモートMCPの認可フローは、401応答をきっかけに次の7段階で進みます。各段階が異なるRFCに対応しており、どれか1つでも欠けると接続できません。

1. 未認証リクエストと401応答: クライアントがトークンなしでMCPサーバーへリクエストを送ると、サーバーは401 Unauthorizedを返し、WWW-Authenticateヘッダーに保護リソースメタデータのURLを載せる
2. 保護リソースメタデータの取得(RFC9728): ヘッダーのresource_metadataで示されたURL、無ければ/.well-known/oauth-protected-resourceを叩き、authorization_serversフィールドから認可サーバーを特定する
3. 認可サーバーメタデータの発見(RFC8414 / OIDC): /.well-known/oauth-authorization-serverと/.well-known/openid-configurationを優先順位付きで試す。取得したメタデータのissuer値が問い合わせ先URLと一致しなければ、そのメタデータは使わない
4. クライアント登録: Client ID Metadata Documents・事前登録・Dynamic Client Registrationの3方式から選ぶ(次節で詳しく扱う)
5. PKCEとresourceパラメータ付きの認可リクエスト: クライアントはcode_challengeを生成し、接続先MCPサーバーの正規URIをresourceパラメータとして認可リクエストとトークンリクエストの両方に含める(RFC8707)。ブラウザでユーザーが認可すると、認可サーバーはコールバックへ認可コードとiss(発行者識別子)を返す
6. iss検証とトークン交換: クライアントは事前に記録した発行者識別子とissを突き合わせ、一致しなければコードをトークンエンドポイントへ渡さない(RFC9207)。一致すればcode_verifierとresourceを添えてトークンを要求し、アクセストークンを受け取る
7. Bearerトークンでのリクエスト: 以降のMCPリクエストにはAuthorization: Bearer <token>ヘッダーを毎回付ける。トークンをURLのクエリ文字列に含めることは仕様で禁止されている

クライアント登録の3方式とDCR非推奨

クライアントは認可リクエストを送る前に、認可サーバーへ自分の身元を示すクライアントIDを持っている必要があります。仕様は3つの登録方式と優先順位を定義しています。

優先順位は「事前登録済みなら事前登録 → 認可サーバーがCIMDに対応していればCIMD → DCRに対応していればDCR → どれも無ければユーザーに手入力させる」の順です。2026-07-28版の仕様は、DCR(RFC7591)をクライアント登録メカニズムとして非推奨にしました。CIMDに対応していない認可サーバーとの後方互換にのみ残す位置づけです。廃止までの猶予期間は12か月以上あり、既存のDCR対応サーバーがすぐ動かなくなるわけではありません。

CIMDが解決するのは、DCRの構造的な弱点です。DCRで発行されたクライアントIDは、発行した認可サーバーに紐づきます。仕様は「クライアント認証情報は発行元の認可サーバーのissuer識別子で管理し、認可サーバーが変わったら再登録が必要」と定めており、サーバーを乗り換えるたびに登録し直す手間が生じます。CIMDのクライアントIDは自分がホストするHTTPS URLそのものなので、認可サーバーが変わってもURLは変わらず、再登録が不要です。

Claude CodeがCIMDに対応したのはv2.1.81(2026年3月)で、DCR非対応サーバーへの主要な回避策として実装されました。DCRにもCIMDにも対応していないサーバーでは、開発者ポータルで事前にOAuthアプリを登録し、発行された認証情報を渡します。

# 事前登録した client_id / client_secret でリモートサーバーを追加
claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

スコープの決め方と追加認可(step-up)の流れ

MCPクライアントは、必要最小限のスコープだけを要求する原則(least privilege)に従います。優先順位は明確です。まず401応答のWWW-Authenticateヘッダーにあるscopeパラメータを使い、それが無ければ保護リソースメタデータのscopes_supported全体を使います。

Claude Codeはこの原則をv2.1.196(2026年6月)で仕様どおりに徹底しました。それ以前は、自動発見した認可サーバーメタデータのscopes_supportedカタログを丸ごと要求していました。その結果、GitLab self-hosted等の一部のエンタープライズIdPで問題が起きていました。管理者専用やテンプレート用のスコープまで宣伝するID基盤が、invalid_scopeエラーで認可リクエストを拒否していたのです。現在はWWW-Authenticateか保護リソースメタデータが示す範囲だけを要求し、どちらも無ければscopeパラメータ自体を送りません。

組織のセキュリティ方針でスコープをさらに絞りたい場合は、.mcp.jsonのoauth.scopesにスペース区切りの文字列を設定します。認可サーバーがより広いスコープを宣伝していても、要求範囲をその設定に固定できるからです。認可サーバーがoffline_accessをscopes_supportedに含めている場合、Claude Codeはこれを自動で追加します。ブラウザでの再ログインなしにトークンを更新するための措置です。

実行中のツール呼び出しが403 insufficient_scopeで拒否されると、クライアントは不足分のスコープを既存のスコープと合わせて要求し直します。これがstep-up認可フローです。仕様は「前回までに要求したスコープと、今回のエラーが示すスコープの和集合を取る」ことを求めており、再認可のたびに以前の権限が失われないようにする設計です。Claude Codeも、固定したoauth.scopesの範囲内でこの再認可を行います。

Claude CodeでリモートMCPを認証する手順

OAuth対応のリモートサーバーは、追加してからセッション内で/mcpを実行し、ブラウザでログインするだけで接続が完了します。取得したトークンは安全に保存され、期限が切れると自動で更新されます。

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

/mcp

セッションを開かずに認証したい場合は、claude mcp login <name>がシェルから直接OAuthフローを実行します(v2.1.186から)。SSHセッションやディスプレイの無いLinux環境ではローカルブラウザが検出できないため、認可URLをそのまま表示するモードに自動で切り替わります(v2.1.191)。--no-browserを付けると、ブラウザがある環境でも強制的にこのモードにできます。

claude mcp login sentry --no-browser

--callback-portは特定のリダイレクトURIをあらかじめ登録しているサーバー向けに、コールバックポートを固定するオプションで、既定ではポートはランダムに選ばれます。一方、.mcp.jsonでheaders.Authorizationを設定したサーバーがそのヘッダーを拒否した場合、Claude CodeはOAuthへフォールバックせず、接続失敗として報告します。トークンの有効性を確認するか、OAuthを使うならヘッダー設定を外します。

非対話モード(claude -pやAgent SDK実行)には/mcpパネルが無いため、Claude Code自身が認可フローを代行できません。v2.1.196からは、ツール検索が有効な状態で未認証のサーバーがあると、Claudeにそのサーバーのツールが使えないことを伝えるようになりました。設定が読めていないかのように振る舞う代わりに、どのサーバーへのサインインが必要かを名指しできます。サインイン自体は対話セッションの/mcpかclaude mcp loginで完了させます。

claude.aiで追加したコネクタ(Google Drive・GitHub・Slack等)は、claude.ai側で認証済みならClaude Codeでも自動的に使えます。ただしMicrosoft 365やGmailなど一部のコネクタは例外です。アップストリームのIDプロバイダーがclaude.aiの登録済みリダイレクトURLしか受け付けないため、Claude Codeからのローカル認証に対応していません。この場合はclaude.aiの「設定 → コネクタ」で接続すると、Claude Code側にも自動的に反映されます。

Claude CodeのOAuth対応はどこまで自動化されたか

Claude Codeのリモートサーバー対応は2025年6月のOAuth初対応から始まり、1年強かけて仕様の主要な要素を取り込んできました。

1年強のあいだで、リモートMCPの認可は「ブラウザでログインできれば動く」実装から、仕様のRFCレベルの細部まで踏み込んだ実装へ着実に積み上がっています。ただし完成しているとは言えません。v2.1.196のスコープ要求変更もv2.1.206のリフレッシュ挙動修正も、2026年に入ってからの改善です。企業のIdP(ADFS・GitLab self-hosted等)との相性問題は、現在も修正が続いている領域です。

エンタープライズ環境でよくあるつまずき

認可サーバーが企業の内製IDプロバイダーだと、公開SaaS向けの実装では想定していない挙動に当たりやすくなります。エラーメッセージと原因の対応関係を押さえておくと切り分けが早くなります。

• 「Incompatible auth server: does not support dynamic client registration」: 認可サーバーがCIMDにもDCRにも対応していません。開発者ポータルで事前にOAuthアプリを登録し、--client-idと--client-secret、登録済みリダイレクトURIと一致する--callback-portを指定して追加し直します
• invalid_scopeで認可リクエストが拒否される: 認可サーバーが管理者専用スコープまでscopes_supportedに宣伝しているケースで、v2.1.195以前ではその全体を要求してしまっていました。v2.1.196以降のバージョンを使っていれば発生しません
• authServerMetadataUrlを設定したのに再起動後に効いていない: v2.1.97 / v2.1.98で修正された、トークン更新時に設定が読み込まれない不具合です。ADFSのような独自のディスカバリー経路を持つIdPで顕在化していました
• コールバックポートがすでに使用中でハングする: v2.1.74で解消済みです。固定ポートを使う場合は、そのポートが他プロセスで使われていないか先に確認します
• 複数のOAuth対応MCPサーバーを使うとキーチェーンが壊れる(macOS): 大きなOAuthメタデータがsecurityコマンドの標準入力バッファを超え、認証情報が破損する不具合でした。関連する競合修正は複数バージョンに分かれて入っています

よくある質問

すべてのトランスポートでOAuthが使えるか

使えません。OAuthに対応するのはStreamable HTTP(と後方互換のSSE)だけです。サーバーからClaudeへ予告なくイベントを送るWebSocketトランスポートは、双方向の常時接続という性質上、OAuthもclaude mcp add --transportフラグも非対応です。認証には別の方式を用意する必要があります。

同じサーバーをClaude Codeとclaude.aiの両方に追加したらどちらが優先されるか

同じURLを指すサーバーがClaude Code側にもclaude.aiのコネクタ側にも存在する場合、Claude Code側で明示的に追加した設定が優先されます。claude.aiコネクタは/mcpの一覧で「重複」として非表示になり、そちら側を使いたければ表示から手順を確認して片方を外せます。

OAuthトークンを取り消したいときはどうするか

/mcpメニューの「Clear authentication」を選ぶと、保存済みのトークンとリフレッシュトークンをその場で失効させられます。次回接続時はブラウザでの認可からやり直しになります。

認可後のブラウザリダイレクトが失敗したらどうするか

自動的なlocalhostへのリダイレクトが接続エラーで失敗した場合でも、認可自体はサーバー側で完了しています。ブラウザのアドレスバーに表示されているコールバックURLをコピーし、Claude Codeが表示するURL入力プロンプトに貼り付ければ、そのまま認証を完了できます。

組織はメンバーが使えるコネクタのツールを制限できるか

TeamプランとEnterpriseプランでは、claude.aiコネクタのツールを「ask」または「blocked」に設定できます。「ask」は呼び出しのたびに組織承認が必要という理由付きで確認を求め、確認を通常スキップするbypassPermissionsのような権限モードでも省略されません。「blocked」はClaudeにツール自体を見せません。ただしこの制御を強制するにはClaude Code v2.1.129以降が必要で、それより古いバージョンは設定を無視して通常の権限フローのまま動きます。また、確認を一切出さないdontAskモードでは「ask」設定のツールは確認ではなく拒否として扱われます。

まとめ

リモートMCPのOAuth認証は、401応答から保護リソースメタデータ・認可サーバー発見・クライアント登録・PKCE付きトークン交換までをつなぐ、RFC群の組み合わせで動いています。2026-07-28版の仕様は、クライアント登録の主軸を変えました。Dynamic Client Registrationから、自己ホスト型のClient ID Metadata Documentsへの移行です。

Claude Code側もv1.0.27での初対応からv2.1.206まで、この仕様変化を1つずつ取り込んできました。日常的な接続はclaude mcp addと/mcpの2手順で完結します。DCR非対応の認可サーバーや企業IdPを相手にする場合だけ、事前登録クレデンシャルやスコープ固定といった一段踏み込んだ設定が必要になります。

claude mcp addの全オプションとスコープ管理の詳細はClaude Code MCP設定ガイドが扱っています。症状別の切り分け手順はMCPサーバーに接続できないときの切り分け手順、自分でOAuth対応のMCPサーバーを作る側の実装はMCPサーバー自作ガイドにまとめてあります。