OpenCode MCP: подключи нужное и проверь, что работает

Чтобы подключить MCP в OpenCode, проверьте версию, добавьте нужный сервер в проект и получите ответ его инструмента. Не ставьте все MCP подряд: OpenCode будет пережирать контекст и лезть не туда.

OpenCode уже должен быть установлен и работать с моделью. Установку и подключение модели я разобрал в отдельной статье. Здесь подключим Context7, чтобы получить документацию нужной библиотеки. Начните с версии клиента.

Какая у вас версия OpenCode? Сначала проверьте

Первая команда в терминале:

opencode --version

Сохраните полный вывод. Для 2.x подходят команды ниже. Если у вас 1.x, сначала перейдите на V2. Если команда не найдена или версия непонятна, выясните, какой клиент запускается. Подключение пока не начинайте.

V2 читает поддерживаемые настройки V1 и преобразует их в памяти, не меняя исходный файл. Переписывать весь конфиг необязательно. Для нового подключения используйте формат V2.

Если обнаружилась V1, сохраните копию настроек и откройте порядок перехода на V2. Обе версии используют одинаковые места конфигурации. Не запускайте V1 с файлом, который уже перевели в формат только для V2.

Если ставили V1 через пакетный менеджер, сначала удалите её тем же менеджером. Установщик V2 через curl сам заменяет прежний исполняемый файл. Способ для своей ОС выберите на странице установки OpenCode, затем снова проверьте версию.

После перехода проверьте модели, учётные данные, агентов, права, MCP и плагины проекта. Плагины V1 требуют переноса на новый API. Если рабочий проект зависит от них, оцените последствия до перехода.

Какой MCP выбрать под вашу задачу? Обсудить можно в канале:

Какие инструменты он даёт и нужен ли вам этот MCP?

Context7 достаёт актуальную документацию библиотеки для задачи агента. Например, как сделать динамический маршрут в Next.js. На таком вопросе и проверим подключение.

Перед установкой откройте сайт разработчика сервера. Посмотрите, откуда берётся сервер, какие инструменты он даёт и какой способ входа необходим.

У OpenCode есть локальные и удалённые подключения. Для local клиент запускает программу через stdio; обязательны type: "local" и массив command. Для remote нужны type: "remote" и полный адрес url; соединение идёт через Streamable HTTP.

Context7 подключим к удалённому серверу. Локальный пакет устанавливать не нужно. Подробнее о внешних подключениях для агента - в статье про MCP-сервер.

У Context7 есть мастер setup, который выполняет вход, создаёт API-ключ и ставит навык. Он предлагает работу через командную строку или MCP. Есть и плагин @upstash/context7-opencode, который добавляет MCP и навык context7-mcp.

Здесь добавим сервер штатной командой OpenCode. Дополнительно запускать мастер и ставить плагин не нужно. При ручном добавлении появится только MCP-подключение, без навыка из плагина.

У ручного подключения и плагина разные заголовки для передачи ключа. Не переносите настройки из одного способа в другой.

Как добавить Context7 в проект и не перепутать настройки?

Откройте терминал в каталоге нужного проекта. Выполните:

opencode mcp add context7 --url https://mcp.context7.com/mcp
opencode mcp list

Первая команда сохраняет сервер в настройках проекта, вторая показывает состояния соединений. Параметр --global добавил бы сервер для всех проектов, но здесь его нет. Дублировать запись в общих настройках не нужно.

Структура ручной записи V2 по полным путям полей:

Точки обозначают вложенность полей. Таблица нужна для сверки или ручной настройки: после команды добавления создавать сервер ещё раз не нужно. Остальные записи сохраните.

Проектный файл может называться opencode.jsonc или opencode.json. Допускаются также .opencode/opencode.jsonc и .opencode/opencode.json. Общие настройки находятся в ~/.config/opencode/opencode.jsonc либо ~/.config/opencode/opencode.json. Создавать все перечисленные файлы не нужно.

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

Для удалённого сервера OAuth включён по умолчанию. Если вы выбрали API-ключ вместо OAuth, измените тот же объект mcp.servers.context7:

• укажите oauth: false;
• добавьте в headers заголовок CONTEXT7_API_KEY;
• значением задайте подстановку переменной окружения CONTEXT7_API_KEY по синтаксису OpenCode.

Сам секрет передайте через окружение процесса OpenCode. В файл проекта, репозиторий, снимок экрана и переписку его не помещайте. Запись $CONTEXT7_API_KEY внутри JSON не раскрывается: синтаксис оболочки здесь не сработает.

Заголовок Authorization из инструкции к плагину здесь не используйте.

Соединение есть. А инструмент действительно ответил?

Посмотрите результат opencode mcp list. Состояние connected означает, что соединение готово к работе. Запрос документации ещё не выполнен.

Проверьте вход, разрешения и ответ инструмента. Вход в модель не означает, что вы вошли в Context7. Даже при готовом соединении вызов инструмента может быть запрещён.

Если требуется вход

При состоянии needs authentication откройте OpenCode, выполните /mcps, выберите Context7 и завершите вход в браузере. Тот же вход можно начать из терминала:

opencode mcp auth context7

После завершения снова выполните opencode mcp list. Учётные данные OAuth хранятся вне конфигурации проекта. Вставлять их в opencode.json не нужно.

Если OpenCode работает на удалённой машине, браузер после входа может открыть недоступную страницу возврата. Скопируйте её адрес и вставьте в ожидающий запрос входа OpenCode. Фактический адрес содержит данные авторизации: не публикуйте его и не включайте в отчёт.

Если соединение есть, проверьте разрешения

Посмотрите действующие permissions. Например, правило с действием context7_*, ресурсом * и эффектом deny запрещает соответствующие инструменты даже при готовом соединении.

Правило проверяется по имени в формате «сервер_инструмент». Найдите имя в записи вызова или каталоге инструментов своей сессии. Если запрет установил администратор или вы ввели его намеренно, согласуйте доступ с владельцем правил. Без разрешения остановитесь.

Разрешать все инструменты всех серверов для проверки Context7 не требуется.

Получите ответ документации

Пример проверочного запроса агенту:

Найдите в документации /vercel/next.js, как устроить динамический маршрут. use context7. Покажите, какой инструмент вызван, с какими аргументами и что вернулось из документации.

Для рабочей задачи укажите используемую версию библиотеки. Если её идентификатор уже известен, передайте его прямо в запросе, как /vercel/next.js в примере.

После ответа откройте запись вызова в сессии. Сравните имя инструмента, аргументы и полученные данные с ответом агента. Фразы «использовал Context7» недостаточно: инструмент должен вернуть сведения по вашей задаче. Почему ИИ-агент может говорить «готово» без выполненной работы, я разобрал в отдельной статье.

Code Mode включён по умолчанию и группирует инструменты по серверу. Список инструментов и вызовы могут выглядеть по-разному в разных режимах. Отключать Code Mode ради привычного списка не нужно. Берите имена из каталога инструментов и записей вызовов своей сессии. Состав плагина не показывает, что доступно при ручном подключении.

Кстати, я снял полный гайд про связку для первого агента Hermes Agent, обязательно посмотрите.

В видео показываю, как выбрать подключения, какие права давать агенту и как сохранить проверенный способ работы в навык. Рабочие сервисы подключаем через MCP и API в Hermes Agent. Это поможет с выбором подключений; настройку Context7 в OpenCode в ролике не показываю.

Что сохранить после проверки

Запишите точную версию OpenCode, способ подключения и где сохранены настройки: в проекте или для всех проектов. Добавьте статус сервера, способ входа и разрешён ли вызов действующими правилами.

Для вызова сохраните имя инструмента, аргументы и ответ с документацией по задаче. Подойдёт фрагмент журнала или снимок с возвращёнными данными без секретов. Рядом оставьте ответ модели для сравнения.

Если инструмент вернул ошибку или сведения по другому вопросу, проверка ещё не закончена.

Хотите собирать свои проекты с ИИ-агентами? Посмотрите программу практикума СмыслоКода.

Практикум по вайб-кодингу

+Твой второй мозг

3 вечера - инструменты, метод, первый проект

Старт 17–19 ноября  ·  2 000 ₽

Записаться →

MCP не работает: где именно остановилось?

Откройте список соединений и запись последней попытки. Найдите свой случай в таблице.

Если сервер не соединён, проверьте общие и проектные настройки. Неполная запись в проекте заменит весь объект сервера, поэтому адрес из общего файла не подхватится. Проверьте обязательные поля в настройках проекта.

Если вызов вернул ошибку, посмотрите, на каком этапе. OpenCode отдельно ждёт запуска соединения (startup), получения списка инструментов (catalog) и ответа инструмента (execution). Ошибка запроса и задержка получения списка - разные сбои.

Не увеличивайте время ожидания, не меняйте ключ и не переустанавливайте клиент наугад. Сначала прочитайте ошибку. Если сервер отклонил аргументы запроса, повторное добавление адреса их не исправит.

После исправления повторите действие, на котором остановились: соединение, вход или вызов инструмента.

Не используете MCP - отключите его

Через MCP агент может как читать, так и отправлять данные во внешний сервис: например, находить клиента в CRM, читать переписку или добавлять заметку в карточку.

Отключать ненужные MCP стоит и ради безопасности: если сейчас не работаете с сервисом, незачем оставлять агенту его инструменты.

Поэтому есть важное правило: не используете MCP, отключите его. Зачем тратить токены?

В OpenCode временно отключить Context7 можно через /mcps. Это действие не меняет файл конфигурации.

Для сохранённого отключения добавьте disabled: true в действующий объект mcp.servers.context7. Состав записи:

Сохраните выбранные параметры авторизации и остальные настройки проекта. При переопределении сервера из общих настроек повторите обязательные поля объекта.

Запустите OpenCode заново. Откройте /mcps и проверьте список соединений: Context7 не должен подключиться автоматически.

Если подключение больше не нужно, удалите его запись из того проектного или общего файла, куда добавляли. Остальные серверы оставьте на месте.

Какой MCP вам нужен для ближайшей задачи и что вы хотите получить от его инструмента? Напишите в комментариях в канале.

Практикум по вайб-кодингу

+Твой второй мозг

3 вечера - инструменты, метод, первый проект

Старт 17–19 ноября  ·  2 000 ₽

Записаться →

Новые материалы - дайджестом, без спама

Гайды выходят регулярно. Подпишись, чтобы не пропускать: пришлю подборку в Telegram или на email. Раз в неделю или каждый день - выбираешь сам.

Подписаться в Telegramили на email