Anthropic MCP Tunnels管理API移行、Admin APIからClaude APIへ切り替える手順

Anthropicは2026年6月22日、研究プレビュー中のMCP Tunnels管理APIを移動した。旧APIはAdmin APIの/v1/organizations/tunnels、新APIはClaude APIの/v1/tunnelsである。

新しいAPIはanthropic-beta: mcp-tunnels-2026-06-22ヘッダーと、Workload Identity Federationのworkspace:manage_tunnelsスコープを使用する。旧APIは移行期間中も利用できるが、終了日が明示されていないため、放置は危険である。

何が変わったか

管理対象が組織パス中心のAdmin APIから、ワークスペースの権限境界を意識したClaude APIへ移った。URLだけでなく、beta headerとWIF scopeも変わる。既存の管理ジョブ、Terraform相当の自動化、監視、秘密情報管理をまとめて確認する必要がある。

変更前後の差

誰に影響するか

MCPサーバーへの私設接続を自動管理する企業、複数ワークスペースでトンネルを作成するPlatformチーム、短期トークンを使うWIF環境、監査ログや構成管理へトンネル情報を取り込む組織に影響する。

期限

旧APIの具体的な停止日は公式リリースノートで明示されていない。したがって移行ウィンドウ中に対応する必要がある変更として扱う。内部期限を設定し、新規作成は新APIへ限定する。

必要な対応

新API用の認証主体を作り、最小権限のworkspace:manage_tunnelsを付与する。既存トンネルの一覧、ID、接続状態、関連MCPサーバーが新旧APIで一致することを確認してから書き込み処理を切り替える。

実装・移行手順

1. 旧APIを呼ぶコード、CI、運用スクリプトを検索する。
2. 対象ワークスペースとトンネルの台帳を作る。
3. 新しいWIF scopeを持つ検証用主体を用意する。
4. /v1/tunnelsへ読み取り要求を送り、件数と属性を比較する。
5. beta headerを共通クライアントへ追加する。
6. 新規作成を新APIへ切り替え、旧APIでは読み取りだけを続ける。
7. 更新・削除の冪等性と権限エラーを試験する。
8. 監視とRunbookのURL、ステータスコード、権限名を更新する。
9. 安定後に旧API呼び出しを削除する。

失敗しやすい点

• URLだけ変更してbeta headerを付けない
• 従来の組織管理権限で新APIも動くと仮定する
• ワークスペース境界を無視して全環境へ同じ主体を使う
• 一覧取得の差分を確認せず削除APIを試す
• 旧APIの成功を監視し続け、新APIの障害を見逃す
• 研究プレビュー機能を無停止前提で本番依存する

リスク

権限不足なら管理操作が停止し、権限過大なら他ワークスペースのトンネルを変更する危険がある。また、トンネル自体が稼働していても管理APIだけが失敗する状態があり、構成変更や証明書更新時に問題が顕在化する。

評価方法

• 新旧APIのトンネル件数・属性一致率
• 作成、更新、削除の成功率
• WIFトークン取得と権限拒否の件数
• 管理API障害時の既存接続継続性
• 変更反映までの時間
• 監査ログで操作主体を追跡できる割合

ロールバック

新APIの書き込みで問題が発生した場合は、新規変更を停止し、移行期間中は旧APIへ書き込みを戻す。作成済みトンネルを即座に削除せず、状態を照合する。認証主体とbeta headerは別Feature Flagにし、原因を切り分けられるようにする。

編集部分析

今回の移行はエンドポイント変更ではなく、管理権限を組織中心からワークスペース中心へ整理する変更である。MCP接続はネットワーク、認証、ツール権限が交差するため、APIクライアントだけを直して完了としない。トンネル台帳、責任者、接続先、権限、停止手順を一体で管理すべきだ。

実務チェックリスト

• [ ] 旧API利用箇所を全件特定した
• [ ] トンネル台帳を作成した
• [ ] workspace:manage_tunnelsを最小権限で付与した
• [ ] beta headerを設定した
• [ ] 新旧一覧の差分を確認した
• [ ] 更新・削除を検証環境で試験した
• [ ] 監視とRunbookを更新した
• [ ] 旧APIへ戻すFeature Flagを用意した

一次情報

• Claude Platform release notes
• Tunnels API reference