Перейти к содержимому
Прогресс курса
0 из 12 модулей

Модуль 6

MCP

Remote- и local-серверы в mcp.servers, инструмент context7 в работе, имена <server>_<tool>, права на инструменты сервера и гигиена контекста.

20 мин

Содержание модуля
  1. Remote-сервер за одну команду
  2. Локальные серверы
  3. Имена и права
  4. Цена контекста и гигиена

Чему научишься

  • подключать remote- и local-серверы командой opencode mcp add и проверять их в /mcps
  • читать и править конфиг mcp.servers: type, url, command, environment, disabled
  • закрывать инструменты серверов правилами permissions и держать конфиг минимальным

Без стандарта каждая связка «агент + внешний сервис» — отдельная интеграция: десять агентов и десять сервисов дают сто интеграций. MCP (Model Context Protocol) решает эту проблему: открытый протокол, по которому любой агент подключается к любому серверу инструментов. Спецификация — modelcontextprotocol.io, каталог серверов — в репозитории MCP на GitHub: документация, базы данных, трекеры, браузеры.

MCP — это USB-порт для инструментов. Подключаешь сервер, и агент получает его инструменты: Context7 даёт поиск по актуальной документации библиотек, сервер БД открывает запросы к данным, сервер трекера управляет задачами. Платой за подключение служит контекст: описания инструментов каждого сервера едут в каждый запрос, поэтому в конфиге держат только серверы с текущими задачами.

Remote-сервер за одну команду

Подключение Context7Дока: MCP-серверы
# remote-сервер (HTTP): команда пишет сервер в opencode.jsonc проекта
opencode mcp add context7 --url https://mcp.context7.com/mcp

# то же сразу для всех проектов
opencode mcp add context7 --global --url https://mcp.context7.com/mcp

# статус серверов из терминала
opencode mcp list

Remote-сервер работает по HTTP и обычно авторизуется OAuth: если opencode mcp list показывает needs authentication, открой OpenCode, выполни /mcps, выбери сервер и войди через браузер. Сервер с API-ключом подключается заголовком; ключ берётся из переменной окружения через {env:ИМЯ} и в файл конфига не попадает.

opencode.jsonc, фрагмент mcp.serversДока: MCP-серверы
{
  "mcp": {
    "servers": {
      "context7": {
        "type": "remote",
        "url": "https://mcp.context7.com/mcp"
      }
    }
  }
}
Флаг --global пишет тот же блок в глобальный конфиг ~/.config/opencode/opencode.jsonc.
Документация внутри диалога

@build проверь по актуальной документации: как в тестах поймать исключение из orderTotal на неизвестном menuId

Проверил через context7: assert.throws из node:assert ловит синхронное исключение, сообщение проверяется регуляркой. Для tests/pricing.test.ts набросал кейс: orderTotal с menuId «nope» бросает /Неизвестная позиция меню/, плюс регресс на quantity −2 из модуля 2. Ссылки на доки Node приложил.

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

Local-сервер — процесс, который OpenCode запускает сам: команда пишется в mcp add после --. Так подключают серверы, которых нет в интернете: работа с браузером через Playwright, доступ к локальной базе, корпоративные инструменты. Флаги --env передают переменные окружения, в конфиге команда превращается в массив command, переменные — в environment с подстановкой {env:ИМЯ}.

Подключение local-сервераДока: MCP-серверы
# демо-сервер MCP для проверки связки
opencode mcp add everything -- npx -y @modelcontextprotocol/server-everything

# с переменной окружения
opencode mcp add everything --env LOG_LEVEL=info -- npx -y @modelcontextprotocol/server-everything
opencode.jsonc, local-серверДока: MCP-серверы
{
  "mcp": {
    "servers": {
      "everything": {
        "type": "local",
        "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
        "environment": { "LOG_LEVEL": "info" }
      }
    }
  }
}
Секреты — в переменных окружения: значение вида "{env:MCP_API_KEY}" подставится при запуске.

Имена и права

Инструмент зовётся <server>_<tool>: имя сервера, затем имя инструмента. Символы вне букв, цифр, подчёркивания и дефиса заменяются на _, сам дефис сохраняется: у Context7 инструмент resolve-library-id остаётся context7_resolve-library-id. Промпты сервера превращаются в команды вида /server:prompt. Право на инструмент — правило permissions, где action равен имени инструмента; deny прячет инструмент без отключения сервера, правило работает и в permissions агента из модуля 4.

opencode.jsonc, фрагмент permissionsДока: permissions
{
  "permissions": [
    { "action": "context7_*", "resource": "*", "effect": "allow" },
    { "action": "playwright_*", "resource": "*", "effect": "deny" }
  ]
}
Инструменты context7 открыты, playwright скрыт у всех агентов проекта при живом сервере.

Цена контекста и гигиена

Каждый подключённый сервер приносит описания своих инструментов в каждый запрос, а свои инструкции — в системный промпт сессии. Пять серверов по десятку инструментов съедают окно, которое нужно коду проекта; симптомы зоопарка и месячный аудит разбираем в модуле 9. Правило простое: подключён значит используется. Временно выключенный сервер описывается полем "disabled": true и не подключается; вернуть — убрать поле. Удалить сервер — стереть запись из mcp.servers.

Практика модуля

  1. Дока: MCP-серверы
    opencode mcp add context7 --url https://mcp.context7.com/mcp
  2. Дока: MCP-серверы
    opencode mcp list
  3. @build проверь по актуальной документации: как в node:test замокать функцию из другого модуля
  4. Дока: MCP-серверы
    opencode mcp add everything -- npx -y @modelcontextprotocol/server-everything
  5. Дока: MCP-серверы
  6. Дока: MCP-серверы

Отмечено 0 из 6

Проверь себя

Вопрос 1 из 4

Прогресс квиза
Что даёт подключение MCP-сервера вроде Context7?

Шпаргалка модуля

Команды

opencode mcp add <имя> --url <адрес>
remote-сервер в конфиг проекта; --global — на все проекты
opencode mcp add <имя> -- <команда>
local-сервер: процесс запускает OpenCode
opencode mcp list и /mcps
статус серверов; в /mcps же вход OAuth

Конфиг mcp.servers

type: remote | local
remote — url по HTTP, local — command-массив
environment: {env:ИМЯ}
переменные сервера; секреты в конфиг не пишут
"disabled": true
выключить сервер, сохранив настройку

Права и имена

<server>_<tool>
имя инструмента; action в permissions равен этому имени
/<server>:<prompt>
промпты сервера становятся командами
deny по имени инструмента
прячет инструмент, сервер остаётся подключён

Ссылки модуля