Xcode 27 mcpbridge 接続失敗では、先にXcodeやAI Agentを再インストールしないでください。まずプロジェクトの開き方、外部AgentのMCP権限、xcrunの参照先、mcpbridgeの登録、同じログインセッションでのBuildとTestを順番に確認し、環境の再構築は最後に判断します。
この手順は、外部 AI Agent からXcode Toolsを呼び出したい独立開発者、SSHやリモートデスクトップでMacを保守する担当者、ソースコード・コマンド・署名権限を分けたい小規模チーム向けです。
最終更新：2026年9月7日。Xcode 27、MCP、外部Agent接続の確認は Appleの外部Agent接続ドキュメント、Xcode 27公式ページ、関連する設定資料を基準にしています。
失敗箇所の切り分け
「Agent一覧ではXcode接続済みなのに、Buildを依頼するとツールが利用できない」という症状は、1つの故障とは限りません。最初に、MCP通信、Xcode Tools、プロジェクト操作のどの層で止まっているかを分けます。
| 表示または症状 | まず確認する対象 | 通過の判断 |
|---|---|---|
| XcodeがAgent一覧に表示されない | mcpbridgeの起動、stdio、Agent設定 | 接続イベントがXcode側に表示される |
| 接続済みだがToolsが空 | プロジェクト、MCP権限、Xcodeの設定 | Xcode Toolsの一覧が取得できる |
| Toolsは見えるがBuildやTestが失敗 | Scheme、作業ディレクトリ、署名、プロジェクト | 読み取り後に最小BuildとTestが完了する |
Appleが案内する外部Agent利用では、対象プロジェクトまたはワークスペースをXcodeで開いておくことが前提です。外部AgentからXcodeへアクセスする公式説明と照合し、複数のプロジェクトを開いている場合は、Agentがどのワークスペースを対象にしているかを確認してください。
Xcode設定とMCP権限の照合
プロジェクトの入口
最初にXcode 27を画面上で起動し、対象のプロジェクトまたはワークスペースを開きます。プロジェクトが閉じた状態でAgentだけを再起動しても、MCPの通信が復旧したように見えるだけで、Xcode Toolsが対象を取得できない場合があります。
次に、Intelligence設定にある外部Agentアクセスの項目を確認します。Appleの Coding Intelligence設定ガイドでは、外部Agentへのアクセスや権限を個別に扱うため、接続許可とコマンド実行許可を同じものとして扱わないでください。
| 確認項目 | 正常な状態 | 不合格時の対応 |
|---|---|---|
| Xcodeのバージョン | 使用対象がXcode 27 | 古いXcodeを開いていないか確認 |
| 対象プロジェクト | プロジェクトまたはワークスペースが開いている | 最小プロジェクトを1つだけ開く |
| 外部Agentアクセス | Intelligence設定で許可済み | 設定変更後に接続を再確認 |
| Xcode側の通知 | 接続またはアクセス要求が表示される | Agent設定と起動入口を記録する |
ここで、内蔵Agent、ACP経由でXcodeに参加するAgent、Xcode外部からMCPで呼び出すAgentを区別します。内蔵Agentが動くことは、外部Agentのmcpbridge設定やstdio通信が正しい証拠にはなりません。権限の詳細は XcodeのAgent権限に関する公式資料で確認できます。
注意：ユーザー名、ホスト名、プロジェクト名、Scheme、作業ディレクトリ、Token、設定ファイル、ログをそのまま共有しないでください。診断時は
<USER>、<HOST>、<PROJECT>、<SCHEME>のような明確な置換名を使い、削除前には設定ファイルをバックアップしてください。
xcrunとmcpbridgeの起動経路
MCP接続の失敗に見えて、実際にはxcrunが別の開発者ディレクトリを見ていることがあります。Xcode本体ではなくCommand Line Toolsや移動済みのアプリケーションを参照していないか、現在値を先に記録します。
xcode-select --print-path
xcrun --find mcpbridge
xcrun mcpbridge
上記は確認用の入口です。実行結果、終了状態、標準エラーを保存し、外部Agentが同じコマンドと環境変数で起動しているかを照合してください。Appleの Xcode 27リリースノートに記載された公開版の挙動と異なる場合は、Xcodeを消す前に開発者ディレクトリ、アプリケーションの場所、Agentの起動設定を戻します。
| 状態 | xcrunの結果 | 次の操作 |
|---|---|---|
| mcpbridgeを解決できない | パスが返らない、またはエラー | 開発者ディレクトリを確認し、変更前の値へ戻せる状態にする |
| 起動直後に切断 | mcpbridgeは見つかるがstdioが終了 | Agentの伝送方式、標準入力、標準エラーを確認 |
| 接続は維持される | Xcode側に接続イベントがある | Tools一覧と読み取り要求へ進む |
設定に古いXcodeパス、重複したXcode MCP項目、公式例と異なる伝送パラメーターが残っている場合は、まず該当項目を無効化します。削除する場合は原ファイルを別名で保存し、復元コマンドまたは復元手順を残してください。
遠隔Macのセッション境界
遠隔 Mac でSSHからAgentを起動する場合、ターミナルが使えることと、XcodeのGUIセッションへ接続できることは別です。リモートデスクトップでログインした状態、GUI上のターミナル、純粋なSSHの3つの入口を比較し、Xcodeウインドウ、プロジェクト、Agentが同じユーザーセッションに属しているか確認します。
| 起動入口 | 確認する境界 | 判定 |
|---|---|---|
| リモートデスクトップ | Xcode画面、プロジェクト、Agentの同一ユーザー | GUI操作を含む検証に向く |
| GUI上のターミナル | Xcodeと同じ環境変数、作業ディレクトリ | mcpbridgeの再現性を確認 |
| SSH | GUIセッション、PATH、権限、作業ディレクトリ | 常駐運用の可否を別途判定 |
ソース以外のディレクトリ、ビルドスクリプト、署名ツールにアクセスさせる場合も、いきなり全ディスクや管理者権限を与えないでください。必要な場所を個別に許可し、拒否された操作のログを残します。接続できない原因を権限拡大だけで解決しようとすると、失敗の境界がさらに不明確になります。
Build・Testによる受け入れ判定
修正後は「接続済み」という表示だけで完了にしません。次の条件分岐で、再構築が必要かを判断します。
- プロジェクトの読み取りが成功し、Tools一覧も取得できるなら、変更を伴わない要求から最小Buildへ進みます。
- 最小Buildは成功するがTestだけ失敗するなら、MCPではなくScheme、テストターゲット、シミュレーター、依存関係を調べます。
- Toolsが表示されてもBuild前に接続が切れるなら、mcpbridgeのstdio、Agent設定、Xcodeのログを再確認します。
- リモートデスクトップでは成功し、SSHだけ失敗するなら、Xcodeを再インストールせず、ユーザーセッションと環境変数の差を直します。
- 最小プロジェクトでも接続、Build、Test、Agent再起動後の再接続が安定しないなら、遠隔Macのセッション維持や環境自体を再構築します。
最後に、公開用証明書や配布Tokenを使わない小さなプロジェクトで、読み取り、Build、Test、Agent再起動、ログインセッション復旧の順に確認します。Appleの Xcode Coding Intelligence資料と WWDC26のXcode 27技術セッションを参照し、Xcode側の権限表示とAgent側の結果を同時に保存してください。
FAQ
接続済みなのにToolsを呼び出せない場合
MCPの通信が存在することと、Xcode Toolsを利用できることは同じではありません。対象プロジェクトの開閉状態、Intelligence設定の外部Agent許可、mcpbridgeの登録、Agent設定の重複を別々に確認します。接続表示だけを根拠にBuildへ進まず、読み取り要求で対象ワークスペースを確認してください。
xcrun mcpbridgeが見つからない場合
使用中のXcode 27ではなく、Command Line Toolsや古いXcodeを参照している可能性があります。xcode-select --print-path と xcrun --find mcpbridge の結果を保存し、開発者ディレクトリを変更する前に元の値と復旧方法を記録します。起動直後の切断ではstdioの伝送設定も確認します。
SSHのAgentから遠隔Macを操作できるか
SSHでコマンドを実行できても、Xcodeが表示されているGUIセッションへ自動的に接続できるとは限りません。リモートデスクトップ、GUIターミナル、SSHの順に同じ読み取り要求を試し、環境変数、作業ディレクトリ、ユーザーセッションの差を記録します。管理者権限の追加は最後の手段です。
BuildとTestの検証方法
まず読み取り専用の要求を実行し、次に配布資格情報を使わない最小BuildとTestを実施します。結果が返ったことだけでなく、Xcode側のログ、Scheme、対象プロジェクトを照合してください。その後にAgent再起動とセッション復旧を試し、再接続後も同じ手順が通るか確認します。
既存のMacでXcodeのGUIセッションを保てない、SSHとリモートデスクトップで結果が毎回変わる、または同じAgent作業を安定して再現できない場合は、何度もXcodeを入れ直すより環境を見直す方が合理的です。手元のMacは常時ログイン、ストレージ確保、電源管理、権限分離を自分で維持する必要があり、短期検証や小規模チームの共有ビルドでは運用負担が残ります。
最小プロジェクトのBuild・Test・再接続まで確認できたら、実際の負荷を遠隔環境で検証してください。購入ではなく必要な期間だけMacを使いたい場合は、VMSPINの日本語案内と料金プランを比較し、利用期間と必要な権限に合う構成を選ぶのが現実的です。物理デバイス接続や長期間の常時高負荷が必要なら自前のMacが適し、臨時のXcode作業、検証、常駐ビルド環境ならVMSPINの遠隔Macを候補にできます。