MCP-серверы

ZubrCode подключается к серверам Model Context Protocol и получает от них инструменты, промпты, ресурсы и инструкции. Инструменты MCP расходуют контекст модели, поэтому подключайте только нужные серверы.

Подключение

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

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

Команда пишет сервер в конфигурацию проекта; --global сделает его доступным во всех проектах. Внутри сессии серверы включаются и выключаются командой /mcps.

zubrcode mcp add context7 --global --url https://mcp.context7.com/mcp

Удалённые серверы по умолчанию используют OAuth. Если в списке написано needs authentication, откройте ZubrCode, выполните /mcps, выберите сервер и войдите. Готовый сервер отмечен так:

✓ context7  connected

Конфигурация

Сервер описывается вручную в opencode.json или opencode.jsonc под mcp.servers — каждому серверу своё уникальное имя:

{
  "mcp": {
    "servers": {
      "my-server": {
        "type": "local",
        "command": ["npx", "-y", "example-mcp-server"]
      }
    }
  }
}

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

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

Локальный сервер — команда, которую ZubrCode запускает через stdio. Добавить с командой после -- и переменными окружения:

zubrcode mcp add everything -- npx -y @modelcontextprotocol/server-everything
zubrcode mcp add everything --env LOG_LEVEL=info -- npx -y @modelcontextprotocol/server-everything

Остальные параметры процесса — в конфигурации:

{
  "mcp": {
    "servers": {
      "everything": {
        "type": "local",
        "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
        "cwd": ".",
        "environment": {
          "LOG_LEVEL": "info",
          "MCP_API_KEY": "{env:MCP_API_KEY}"
        }
      }
    }
  }
}

Поле	Обязательно	Описание
type	да	"local"
command	да	исполняемый файл и его аргументы
cwd	нет	рабочий каталог процесса; относительные пути — от рабочей папки
environment	нет	строковые переменные окружения процесса
disabled	нет	true — не подключаться
codemode	нет	false — инструменты напрямую, а не через Code Mode
timeout	нет	свои таймауты для этого сервера
protocol	нет	legacy (по умолчанию), auto или 2026-07-28

Подстановка переменных окружения — {env:ИМЯ}: выражения оболочки вроде $NAME в JSON не раскрываются.

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

Удалённый сервер использует транспорт Streamable HTTP и требует абсолютный URL. Заголовки передаются повторяющимися --header:

zubrcode mcp add context7 --url https://mcp.context7.com/mcp --header 'CONTEXT7_API_KEY={env:CONTEXT7_API_KEY}'

В конфигурации — type: "remote", url, headers, oauth:

{
  "mcp": {
    "servers": {
      "context7": {
        "type": "remote",
        "url": "https://mcp.context7.com/mcp",
        "oauth": false,
        "headers": {
          "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
        }
      }
    }
  }
}

Секреты держите в переменных окружения, а не в файле. oauth: false используйте только для серверов с ключом или другим заголовочным доступом.

OAuth

Для удалённых серверов OAuth включён по умолчанию: ZubrCode находит сервер авторизации, входит по PKCE и обновляет токены; учётные данные хранятся вне конфигурации проекта. Вход запускается в /mcps или командой:

zubrcode mcp auth sentry
zubrcode mcp logout sentry   # забыть сохранённые OAuth-учётные данные

Если провайдер выдал клиентские ключи, пропишите их в oauth:

{
  "mcp": {
    "servers": {
      "company-tools": {
        "type": "remote",
        "url": "https://mcp.example.com/mcp",
        "oauth": {
          "client_id": "{env:MCP_CLIENT_ID}",
          "client_secret": "{env:MCP_CLIENT_SECRET}",
          "scope": "tools:read tools:execute",
          "callback_port": 19876,
          "redirect_uri": "http://127.0.0.1:19876/callback"
        }
      }
    }
  }
}

Поле	Описание
client_id	id заранее зарегистрированного клиента (важнее автоматической регистрации)
client_secret	секрет конфиденциального клиента; для публичного не указывается
scope	запрашиваемые области через пробел
callback_port	локальный порт обратного вызова, 1–65535
redirect_uri	зарегистрированный loopback-адрес обратного вызова
auth_server_metadata_url	адрес метаданных сервера авторизации, если MCP-сервер его не публикует

Таймауты

Положительные целые миллисекунды. Общие значения — под mcp.timeout, свои timeout у сервера их перекрывают:

Таймаут	По умолчанию	Применяется к
startup	30 секунд	соединение и инициализация сервера
catalog	30 секунд	получение списков инструментов, промптов и ресурсов
execution	12 часов	вызовы инструментов, чтение промптов и ресурсов

Имена инструментов и промпты

Инструмент получает имя <сервер>_<инструмент>: все символы, кроме букв, цифр, _ и -, заменяются на _ (сервер context 7 и инструмент resolve.library/id дают context_7_resolve_library_id). Промпты сервера становятся командами вида /context_7:find_docs, их аргументы передаются по порядку через пробел.

Разрешения и ресурсы

По умолчанию инструменты MCP доступны через Code Mode; codemode: false оставляет их в родном списке инструментов провайдера. Скрыть или запретить инструменты, не отключая сервер, можно правилами разрешений по нормализованному имени:

{
  "permissions": [
    { "action": "context7_*", "resource": "*", "effect": "deny" }
  ]
}

Ресурсы серверов читаются встроенными инструментами; ими управляют действия opencode_list_mcp_resources (ресурс — имя сервера) и opencode_read_mcp_resource (ресурс — <сервер>:<uri>).

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

Управление

zubrcode mcp list                      # серверы и состояние соединения
zubrcode mcp add sentry --url https://mcp.sentry.dev/mcp
zubrcode mcp auth sentry
zubrcode mcp logout sentry

Убрать сервер — удалить его запись из конфигурации проекта или глобальной. Отключение в /mcps конфигурацию не меняет; для настроек OAuth, таймаутов и рабочих каталогов правьте конфигурацию напрямую.