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 может скачивать пакет при запуске, поэтому на рабочем проекте сначала проверяйте источник пакета и правила установки программ. Если нужен только обзор возможностей без запуска стороннего кода, изучите документацию сервера и отложите подключение.

По теме: OpenCode и Codex: как подключить OpenAI в 2026 году

Как подключить удалённый 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-инструментами на уровне общей конфигурации и отдельного агента. Не пытайтесь исправить проблему выдачей более широких прав, пока не знаете её причину.

По теме: OpenCode с Claude: подключение и безопасная настройка в 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 для его записи. Это поддерживаемая настройка.