Сбой подключения внешнего AI Agent к Xcode 27: как исправить mcpbridge в 2026?

Сначала разделите проблему на слой подключения, слой инструментов и слой проекта — не переустанавливайте Xcode или AI Agent до этой проверки. Такой порядок подходит, если Xcode 27 уже открыт, но внешний AI Agent не читает проект, не запускает Build или Test, а на удалённом Mac дополнительно мешает пользовательская графическая сессия.

Кому пригодится этот материал

Он предназначен для независимых разработчиков, которые вызывают Xcode Tools через внешнего AI Agent из командной строки и получают неполный или нестабильный доступ.

Руководство также пригодится тем, кто обслуживает Mac через SSH или удалённый рабочий стол, а небольшой команде поможет встроить AI-помощника в сборку, сохранив ограничения для исходников, команд и сертификатов.

Важно: имя пользователя, адрес узла, название проекта, Scheme, рабочий каталог, репозиторий, токены и журналы ниже обозначаются как <USER>, <HOST>, <PROJECT>, <SCHEME> и <PATH>. Не вставляйте реальные секреты в отчёты об ошибках.

Временная шкала диагностики

На первом этапе сохраните исходное состояние: текст ошибки, список MCP-инструментов, активный путь Xcode и способ запуска Agent. Не исправляйте сразу несколько переменных. Иначе после перезапуска вы не узнаете, помогло ли изменение разрешений, смена Developer Directory или повторная регистрация mcpbridge.

Проверка должна идти по такой временной шкале:

• Момент A — базовая связь. Agent запускается, устанавливает MCP-соединение и показывает доступный набор инструментов.
• Момент B — контекст проекта. Xcode 27 открыт с нужным проектом или рабочей областью, а внешний Agent видит именно этот контекст.
• Момент C — вызов инструмента. Выполняется безопасный запрос только для чтения без изменения файлов.
• Момент D — реальная работа. Запускаются минимальные Build и Test.
• Момент E — восстановление. Agent перезапускается, соединение восстанавливается, а пользовательская сессия снова доступна.

Если сбой происходит между моментами A и B, ищите проблему в MCP или запуске mcpbridge. Если список инструментов есть, но Build и Test не выполняются, не называйте это автоматически сбоем MCP: причина может быть в Scheme, зависимостях, рабочем каталоге, подписи или проекте.

По состоянию на 7 сентября 2026 года Apple описывает доступ внешних агентов к возможностям Xcode через MCP, использование открытого проекта и настройку доступа в Xcode. Эти условия подтверждены в документации Apple о доступе внешних агентов к Xcode, а актуальные сведения о Xcode 27 собраны на официальной странице Xcode.

Состояние проекта и разрешений

Начните не с терминала, а с Xcode. Откройте <PROJECT>.xcodeproj или <PROJECT>.xcworkspace в Xcode 27 и убедитесь, что в окне отображается нужный проект. Если одновременно открыты несколько рабочих областей, временно закройте лишние: внешний Agent может быть подключён к Xcode, но работать не с тем проектом, который вы проверяете.

Apple связывает возможности внешнего агента с уже открытым проектом. Поэтому фраза «Xcode подключён» не означает, что Agent получил контекст нужной рабочей области. Сначала проверьте проект вручную, затем повторите запрос только для чтения — например, запросите список доступных целей или описание текущего проекта без изменения файлов.

Далее откройте настройки Intelligence и проверьте разрешение для внешних агентов. Название пункта и расположение элементов нужно сверять с текущей сборкой: Apple отдельно документирует настройку Coding Intelligence и доступ внешних Agent в руководстве по настройке Coding Intelligence. Не переносите название переключателя из старого снимка экрана или чужой конфигурации.

Разделяйте три состояния:

• Agent не запускает MCP-транспорт или не показывает подключение;
• Agent подключён, но список Xcode Tools пуст или неполон;
• инструменты видны, однако конкретный Build или Test возвращает ошибку.

Для первого состояния проверяйте запуск. Для второго — проект и разрешения. Для третьего — параметры проекта. Такая классификация предотвращает удаление рабочей конфигурации из-за обычной ошибки компиляции.

Инструментальный путь xcrun и mcpbridge

Следующий слой — активный Developer Directory. В графическом интерфейсе может быть открыт Xcode 27, а команда из внешнего Agent при этом использовать старый Xcode, отдельный каталог Command Line Tools или путь к приложению, которое было перемещено. До изменения настройки сохраните результат:

xcode-select -p
xcrun --find mcpbridge
xcrun --version

Пути в выводе замените на <DEVELOPER_DIR> при передаче отчёта команде или в тикет. Если xcrun --find mcpbridge не возвращает исполняемый файл, сначала выясните, какой Developer Directory активен. Не начинайте с переустановки Xcode: это уничтожает полезную информацию о причине и может затронуть рабочие проекты, плагины и локальные сертификаты.

Если на Mac установлено несколько версий Xcode, временно укажите нужный путь в контролируемой сессии и запишите прежнее значение. Для проверки можно использовать переменную окружения:

export DEVELOPER_DIR="/Applications/<Xcode-27>.app/Contents/Developer"
xcrun --find mcpbridge

Не подставляйте путь из примера без проверки фактического имени приложения. После диагностики верните прежнюю настройку или явно зафиксируйте новую в документе команды. Информация о связке Xcode, MCP и mcpbridge приведена в техническом видео WWDC26 о возможностях Xcode 27.

Внешний Agent должен запускать MCP через согласованный stdio-транспорт. Если процесс немедленно завершается, сохраните стандартный вывод и стандартную ошибку:

xcrun mcpbridge 2> /tmp/<PROJECT>-mcpbridge.stderr
printf '%s\n' $?

Эта команда предназначена для диагностики способа запуска, а не для постоянной ручной работы. Закройте процесс после проверки и не публикуйте файл журнала вместе с токенами или путями к закрытым репозиториям.

Конфигурация Agent и границы доступа

Сравните конфигурацию внешнего Agent с официальным способом подключения, но не копируйте чужой файл целиком. Ищите четыре класса ошибок:

• дублирующиеся записи Xcode MCP;
• путь к старому Xcode или удалённому скрипту;
• несовместимый тип транспорта;
• параметры, которые относятся к другому Agent или другому режиму запуска.

Сначала отключите конфликтующую запись, а не удаляйте её. Перед редактированием скопируйте файл:

cp "<PATH>/<agent-config>.json" "<PATH>/<agent-config>.json.backup"

После этого перезапустите только внешний Agent и сравните список инструментов. Если результат не изменился, восстановите резервную копию и переходите к следующему уровню. Удаление записи имеет последствия: можно потерять рабочие параметры, локальные разрешения или настройки другого проекта.

Отдельно различайте:

• встроенного в Xcode Agent;
• Agent, добавленного через ACP;
• внешнего Agent, который обращается к Xcode через MCP;
• процесс mcpbridge;
• обычные команды терминала;
• инструменты Xcode для Build и Test.

Эти сущности могут находиться в одном рабочем процессе, но их права и точки отказа различаются. Настройки полномочий не следует расширять до полного диска или прав администратора только потому, что Agent получил отказ. Apple описывает отдельные границы для действий Agent в документации о расширении и настройке агентов.

Сравнение входов и сеансов

Удалённый Mac добавляет ещё одну переменную: команда может запускаться не в той пользовательской сессии, где открыт Xcode. Сравните три входа — удалённый рабочий стол, графический терминал внутри этой сессии и чистый SSH. В каждом случае зафиксируйте:

• видит ли пользователь окно Xcode;
• открыт ли <PROJECT>;
• одинаковы ли $HOME, $PATH и DEVELOPER_DIR;
• доступен ли mcpbridge;
• возвращает ли Agent результат запроса только для чтения.

Эта таблица не является обещанием одинакового поведения на всех удалённых Mac. Конкретные результаты зависят от способа входа, политики сеанса, настроек безопасности и конфигурации Agent. Apple подтверждает возможности MCP и требования к проекту, но не гарантирует работу каждой сторонней схемы запуска или каждого варианта удалённой сессии; это следует отделять от официальных сведений в документации Coding Intelligence.

Если SSH видит файлы, но внешний Agent не получает Xcode Tools, не выдавайте ему права администратора. Сначала запустите проверку из активной графической сессии. Затем выясните, нужен ли Agent доступ к каталогу исходников, Derived Data, скриптам сборки или инструментам подписи. Для каждого дополнительного каталога оформляйте отдельное разрешение и сохраняйте запись об отказе.

Граница безопасности: исходники, сертификаты, ключи публикации и рабочие каталоги — разные ресурсы. Доступ к одному из них не должен автоматически открывать остальные.

Приёмка через Build, Test и восстановление

Когда соединение и список инструментов подтверждены, переходите к реальному проекту по нарастающей нагрузке. Не начинайте с архивации и публикации: она одновременно затрагивает подпись, ключи, зависимости и сетевой доступ.

Последовательность приёмки:

• Выполните запрос только для чтения и убедитесь, что Agent возвращает содержимое или состояние нужного проекта.
• Запустите минимальный Build для выбранной Scheme без публикационных действий.
• Проверьте, что результат Build вернулся в Agent, а не только появился в локальном терминале.
• Запустите минимальный Test с известным набором тестов.
• Сохраните текст ошибки, активную Scheme и рабочий каталог.
• Перезапустите Agent и повторите запрос только для чтения.
• Разорвите и восстановите удалённую сессию, после чего повторите Build или безопасную часть проверки.

Если первая сборка завершается ошибкой компиляции, MCP может быть полностью исправен. Проверьте зависимости, версию SDK, Scheme, переменные окружения и файлы проекта. Если Agent не может получить результат инструмента, вернитесь к транспортному уровню и журналу mcpbridge.

Apple регулярно меняет детали предварительных выпусков и поведения инструментов. Поэтому названия настроек, команды и ограничения нужно сверять с заметками о выпуске Xcode 27, особенно после обновления малой версии. Следующая проверка необходима при изменении MCP или ACP, поведения mcpbridge, формата конфигурации Agent либо способа запуска на удалённом Mac.

Условия выбора следующего шага

• Если проект открыт в Xcode 27, разрешение внешнего Agent включено, xcrun находит mcpbridge, а запрос чтения работает, то переходите к минимальным Build и Test.
• Если Agent подключён, но инструменты Xcode не отображаются, то проверяйте разрешение, открытую рабочую область и дублирующиеся записи MCP.
• Если mcpbridge не находится, то фиксируйте старый Developer Directory и корректируйте его; не переустанавливайте Xcode по умолчанию.
• Если инструменты отображаются, но Build или Test завершается ошибкой, то переключайтесь на диагностику проекта и не удаляйте конфигурацию MCP.
• Если через графический терминал всё работает, а через SSH нет, то меняйте пользовательскую сессию или способ запуска, а не расширяйте права.
• Если минимальный проект стабильно проходит Build, Test и восстановление соединения, то проверяйте реальный проект с ограниченными секретами.
• Если даже минимальный проект не выдерживает повторного подключения и восстановления сессии, то рассматривайте исправление или замену удалённого Mac.

Восстановление удалённого окружения

Пересоздание среды оправдано только после сохранения диагностической базы. Зафиксируйте активный Xcode, Developer Directory, конфигурацию Agent, способ входа, рабочий каталог и последовательность команд. Иначе новый Mac может временно скрыть проблему, но вы не поймёте, была ли причина в сеансе, пути инструментов или правах.

Для удалённой разработки важна не только доступность macOS. Нужен Mac, на котором можно поддерживать графическую сессию Xcode, открыть проект, запустить внешний Agent и восстановить процесс после разрыва соединения. Перед переносом реального репозитория проверьте минимальный проект и выполните безопасный Build и Test без ключей публикации.

Если собственный Mac не удерживает такую сессию или используется несколькими задачами, можно сравнить варианты удалённого Mac для разработки и отдельно оценить тарифы VMSPIN. Это имеет смысл именно после технической приёмки, а не вместо неё: аренда не исправит ошибочную Scheme, повреждённую зависимость или неверный MCP-путь.

Частые вопросы

Почему подключение отображается, а инструменты недоступны?

Потому что MCP-соединение и доступ к инструментам — разные этапы. Проверьте открытый проект, разрешение внешнего Agent, список Xcode Tools и активный mcpbridge. Если инструменты видны, но команда Build завершается ошибкой, анализируйте проект, Scheme и зависимости, а не повторяйте регистрацию MCP.

Что проверять при мгновенном отключении mcpbridge?

Сохраните стандартную ошибку и код завершения, затем сравните xcode-select -p с путём Xcode 27 и проверьте xcrun --find mcpbridge. Убедитесь, что Agent использует ожидаемый stdio-транспорт. Не удаляйте конфигурацию до создания резервной копии и не меняйте сразу несколько параметров.

Работает ли управление Xcode через SSH?

SSH может запустить процесс и проверить файловую систему, но не всегда предоставляет тот же графический пользовательский контекст, в котором открыт Xcode. Сравните SSH с удалённым рабочим столом и терминалом внутри активной сессии. Если Agent работает только во втором варианте, зафиксируйте это ограничение вместо выдачи лишних прав.

Как подтвердить настоящую работоспособность Agent?

Одного статуса «подключено» недостаточно. Выполните запрос только для чтения, минимальные Build и Test, затем перезапустите Agent и восстановите удалённую сессию. Успешной считается цепочка, в которой Xcode возвращает результат каждого действия, а не просто принимает команду. После этого повторите проверку на реальном проекте без публикационных секретов.

Итог для выбора среды

Существующий Mac остаётся разумным вариантом, если он стабильно удерживает графическую сессию, mcpbridge находится в правильном Developer Directory, а Agent проходит Build, Test и восстановление соединения. Если же текущая машина уходит в сон, теряет Xcode-сеанс, используется несколькими независимыми задачами или не позволяет воспроизводимо проверить удалённый запуск, постоянные переустановки только увеличивают время простоя.

По сравнению с локальным Mac такой подход требует отдельно учитывать состояние сети, задержку удалённого доступа и правила сохранения сессии. Но покупка отдельного компьютера ради нерегулярной отладки также создаёт расходы на оборудование, обслуживание и постоянную доступность. После успешной минимальной приёмки можно проверить варианты заказа VMSPIN и выбрать аренду Mac для временного проекта, удалённого CI или контролируемого тестирования Agent. Для длительной нагрузки с физическими устройствами, постоянными секретами или требованиями к локальным интерфейсам собственный Mac может оставаться более подходящим решением.

Последняя проверка: 7 сентября 2026 года. Факты о Xcode 27, MCP, внешних Agent и mcpbridge сверены по официальной документации Xcode, странице Xcode 27, материалам WWDC26 и заметкам о выпуске; поведение сторонних Agent и удалённых сеансов не рассматривается как гарантия Apple.