MCP в opencode: подключение локальных и удалённых серверов

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

Все параметры сверены с разделом MCP servers документации opencode.ai/docs на 18 октября 2026. Названия ключей берите оттуда, если ваша версия отличается.

Как opencode понимает MCP

Серверы описываются в opencode.json в блоке mcp. Ключ в нём — уникальное имя сервера, и по нему вы можете сослаться на сервер в запросе. После подключения инструменты сервера доступны модели наравне со встроенными. Отключить сервер без удаления можно полем "enabled": false.

Два типа серверов: local (opencode сам запускает процесс на вашей машине) и remote (сервер уже работает по адресу, opencode ходит к нему по сети).

Локальный сервер

Тип local требует command — массив из команды и аргументов:

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

Остальные параметры из документации: cwd (рабочий каталог процесса, относительные пути считаются от рабочего пространства), environment (переменные окружения) и timeout (время в миллисекундах на получение списка инструментов, по умолчанию 5000). Если сервер стартует долго, например, при первом npx скачивает пакет, поднимите timeout, иначе инструменты не успеют зарегистрироваться.

Чтобы проверить, достаточно попросить в чате, как в примере из документации: use the mcp_everything tool to add the number 3 and 4. Имя сервера в запросе подсказывает модели, какие инструменты брать.

Удалённый сервер

Для remote обязателен url. Если сервер требует заголовок, добавьте headers:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
      }
    }
  }
}

Значение через {env:ИМЯ} берётся из окружения, поэтому секрет не попадает в файл, который вы кладёте в git. Это тот же приём, что и для ключа модели.

OAuth

Если сервер требует OAuth, opencode сам обрабатывает ответ 401 и запускает процесс авторизации, а при поддержке динамической регистрации клиента (RFC 7591) ничего больше настраивать не нужно. Для заранее зарегистрированных клиентов в блоке oauth задаются учётные данные. Авторизацию можно запустить вручную:

opencode mcp auth sentry

Пример из документации с Sentry: "type": "remote", "url": "https://mcp.sentry.dev/mcp", "oauth": {}. После авторизации инструменты Sentry доступны в запросах: «покажи последние нерешённые проблемы, use sentry».

Figma и другие MCP-серверы

Запрос «opencode figma mcp» встречается часто, но универсального рецепта здесь нет. У Figma есть собственная инструкция по MCP, и в opencode это такой же блок mcp: либо remote с адресом, либо local с командой запуска, в зависимости от того, какой вариант сервера вы используете. Точные адреса, названия инструментов и требования к тарифу берите из документации Figma, мы их здесь не повторяем, чтобы не вводить в заблуждение. Тот же принцип работает для любого сервера, у которого есть инструкция по подключению к MCP-клиентам.

Ограничить сервер конкретным агентом

Документация предупреждает прямо: MCP-серверы добавляют инструменты в контекст, и некоторые, например GitHub MCP, могут почти целиком съесть его. Поэтому если серверов много, их стоит включать по агентам:

1. Отключите сервер для всех через шаблон имён в tools.
2. В описании нужного агента включите его снова.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  },
  "tools": { "sentry*": false },
  "agent": {
    "triage": {
      "description": "Разбирает ошибки из Sentry",
      "mode": "subagent",
      "tools": { "sentry*": true }
    }
  }
}

Инструменты MCP регистрируются с префиксом из имени сервера. Шаблон sentry* отключит или включит их все разом, а sentry_* сработает точнее. В разделе про агентов документация отмечает, что tools устарело в пользу permission, а подстановочные имена работают и там: например, "sentry_*": "deny". Если сомневаетесь, какой вариант поддерживает ваша версия, проверьте раздел Agents.

Сколько стоят лишние инструменты

Описания инструментов отправляются модели в каждом запросе. Возьмём условное число: допустим, подключённые серверы добавляют 15 000 токенов описаний, а сессия делает 40 запросов. Это 15 000 × 40 = 600 000 токенов входа только на описания.

Цены Zukko на 18 октября 2026 для claude-sonnet-5 ($ за 1M токенов): вход 0.4, чтение кэша 0.05.

• Без кэша: 0.6 × 0.4 = $0,24.
• Если описания читаются из кэша (Anthropic-формат): 0.6 × 0.05 = $0,03, плюс единовременная запись кэша.

Число 15 000 здесь иллюстрация, а не измерение: реальный размер зависит от серверов. Узнать его можно, сравнив расход одной и той же короткой задачи с сервером и без. Кэш виден шлюзу, когда Claude подключён как провайдер anthropic с адресом https://api.zukko.pro/v1, как описано в документации по opencode↗. В OpenAI-формате для Claude весь вход идёт по цене входа.

Если инструменты не появились

• Проверьте timeout и что команда запускается в обычном терминале.
• Убедитесь, что enabled не равен false, а шаблон в tools не запрещает сервер глобально.
• Для удалённых серверов проверьте заголовки и OAuth.
• Выбранная модель должна уметь вызывать инструменты. Если агент отвечает, что не видит ни файлов, ни инструментов, смотрите статью про tool calling↗.
• Ответ 404 на самом запросе к модели — это уже вопрос провайдера, а не MCP: в opencode адрес Zukko должен быть https://api.zukko.pro/v1.

Безопасность отдельно. Всё, что вернул MCP-сервер, модель читает как текст: в тексте тикета или страницы может оказаться инструкция, адресованная агенту. Давайте серверам минимальные права, не включайте автоматическое подтверждение на опасные действия и храните ключи в окружении. Ключ для самой модели заведите отдельный на странице API-ключей↗ с дневным лимитом.

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

Где лежит конфиг, глобальный или проектный?

И так, и так. Глобальный: ~/.config/opencode/opencode.json, проектный: opencode.json в корне. Проектный приоритетнее, значения сливаются, поэтому общие серверы можно держать глобально.

Сколько серверов можно подключать?

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

Как подключить локальный сервер на Python?

Тип local, команда в массиве, например ["python", "/путь/server.py"]. Переменные окружения передайте через environment.

Чем MCP отличается от вызова функций у модели?

Вызов функций — возможность модели просить выполнить инструмент. MCP — стандарт, по которому набор инструментов подключается извне. Больше в статье MCP-сервер: что это и как подключить↗.