OpenCode и MCP-серверы: подключение и проверка в 2026

MCP-серверы в OpenCode подключают внешние инструменты к агенту. Для первого опыта добавьте один сервер в конфигурацию проекта, проверьте его в списке и дайте безопасную задачу чтения. Ниже показаны локальное и удалённое подключение по схеме OpenCode v1, а также способ остановить сервер без удаления настроек. В OpenCode v2 примеры ниже не подходят: серверы записываются в mcp.servers, а отключаются через disabled; ссылка на документацию v2 приведена в разделе ошибок.

Что выбрать: локальный или удалённый сервер

В документации OpenCode есть два типа: локальный процесс запускается командой на вашем компьютере, удалённый доступен по сетевому адресу. Локальный вариант подходит, если инструмент должен читать доступные вам файлы или работать с установленной программой. Удалённый подходит, если сервис предоставляет официальный адрес MCP. В обоих случаях возможности зависят от самого сервера, а не от одного слова MCP.

• Локальный сервер: перед подключением выясните, кто выпустил пакет, какие команды он запускает и к каким файлам получит доступ.
• Удалённый сервер: проверьте адрес и владельца сервиса, условия авторизации и передачу данных наружу.
• Для первой проверки выбирайте сервер с инструментами чтения или тестовыми операциями; доступ на запись подключайте только под конкретную задачу.
• Не добавляйте сразу много серверов: каждый расширяет список инструментов и контекст модели.

OpenCode предупреждает, что большое количество MCP-инструментов увеличивает расход контекста. Поэтому правило выбора простое: один проверенный сервер под один результат, затем оценка пользы. Общее объяснение MCP поможет, если непонятно, чем сервер отличается от самого агента.

Где хранится настройка

Официальная конфигурация OpenCode использует файл opencode.json или opencode.jsonc. Для проекта укажите сервер в объекте mcp с уникальным именем. Перед правкой сохраните копию существующего файла, если в нём уже есть модели, разрешения или другие серверы. Не заменяйте конфигурацию целиком только ради одного блока.

Ниже схема из текущей документации OpenCode для локального тестового сервера. Название mcp_everything здесь только метка. Пакет @modelcontextprotocol/server-everything приведён в официальном примере как демонстрационный, его не следует считать рабочим подключением к вашей базе или почте.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
      "enabled": true
    }
  }
}

Файл примера не содержит секретов. npx может скачивать пакет при запуске, поэтому на рабочем проекте сначала проверяйте источник пакета и правила установки программ. Если нужен только обзор возможностей без запуска стороннего кода, изучите документацию сервера и отложите подключение.

По теме: Codex WSL: как запустить в Linux на Windows и проверить работу

Как подключить удалённый MCP

Для удалённого сервера в официальной схеме указываются type: remote и url. Адрес берите из документации самого провайдера, а не из случайного списка. У OpenCode может включиться вход через OAuth, если сервер его требует. Для сервера с ключом не вставляйте настоящий ключ прямо в публикационный пример или общую конфигурацию проекта.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "docs-remote": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "enabled": true
    }
  }
}

Адрес mcp.example.com условный и не является работающим сервером: замените его официальным адресом выбранного поставщика. Для авторизации OpenCode описывает автоматический OAuth и команду opencode mcp auth <имя>, если вход не запустился сам. Откройте окно входа только после сверки домена поставщика. Не публикуйте файл с токенами и не отправляйте его в чужой репозиторий.

Как проверить подключение и инструмент

Документация OpenCode предлагает посмотреть состояние командой opencode mcp list. Этого мало для проверки пользы: подключённый сервер может отвечать, но не содержать нужного инструмента или не иметь требуемых прав. Проверяйте в два этапа.

1. Откройте проект с изменённой конфигурацией и выполните opencode mcp list. Найдите имя сервера и статус.
2. Если удалённый сервер требует входа, завершите официальный OAuth-поток и повторите список. Не пересылайте секреты в чат.
3. Попросите OpenCode назвать доступные инструменты конкретного сервера и выполнить безопасную операцию чтения или тестовый вызов.
4. Сравните ответ с первичным источником: файлом, документом или тестовой записью, к которой у вас есть доступ.
5. Проверьте, что инструмент не сделал лишних изменений. Для проекта с Git просмотрите разницу файлов; внешние сервисы проверьте в их собственном журнале.

Если сервер сообщает connected, но агент не находит инструмент, назовите сервер явно в задаче и проверьте, не отключены ли его инструменты настройками. OpenCode описывает управление MCP-инструментами на уровне общей конфигурации и отдельного агента. Не пытайтесь исправить проблему выдачей более широких прав, пока не знаете её причину.

По теме: Codex не устанавливается: диагностика по этапам в 2026

Что делать при ошибке или сомнительном сервере

Разделите сбои по признакам. «Не найден процесс» у локального сервера означает проблему команды или пакета. «Нет соединения» у удалённого требует проверки адреса и сети. «Требуется вход» относится к авторизации, а «инструмент недоступен» может означать отсутствие нужных прав или настройку инструментов.

• Локальный сервер не запускается: повторно проверьте команду из документации его автора в отдельном терминале, затем верните прежнюю конфигурацию при ошибке.
• Удалённый сервер не отвечает: сверьте полный адрес с официальной документацией поставщика и его состояние; не заменяйте его произвольным похожим доменом.
• Вход не завершается: проверьте статус через opencode mcp list и повторите opencode mcp auth <имя> только на проверенном сервере.
• Нужный инструмент не появился: убедитесь, что сервер действительно предоставляет его и не отключён настройками OpenCode.
• После подключения ответы стали хуже или слишком длинными: временно отключите сервер и сравните на той же задаче.

Чтобы остановить сервер без потери настроек, поставьте "enabled": false в его записи. Это штатный способ OpenCode. Для уже выданной OAuth-авторизации документация описывает opencode mcp logout <имя>; отключение в файле само по себе не всегда равно отзыву доступа на стороне поставщика.

Безопасный выход: верните сохранённую конфигурацию, отключите сервер и проверьте, что он исчез из активного списка. Не держите ненужный доступ «на всякий случай».

При копировании чужого примера проверяйте версию документации: у новой ветки OpenCode v2 расположение серверов в конфигурации отличается от приведённого здесь. Не смешивайте фрагменты из разных схем. Если ваша установка явно относится к v2, следуйте её документации целиком.

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

Можно ли подключить несколько MCP-серверов?

Да, OpenCode разрешает несколько записей в объекте mcp, но добавляйте их по одной и проверяйте каждую.

Где посмотреть, подключился ли сервер?

Выполните opencode mcp list; это официальная команда для списка и статуса.

Нужно ли добавлять ключ в opencode.json?

Не кладите действующий секрет в файл проекта. Документация OpenCode описывает авторизацию и подстановку переменных окружения.

Как временно выключить сервер?

Установите "enabled": false для его записи. Это поддерживаемая настройка.