MCP и интеграции

Если базовые встроенные инструменты OpenCode работают внутри репозитория, то MCP позволяет подключать внешние системы: документацию, issue tracker, observability, кодовый поиск, базы знаний и многие другие источники данных и действий. Но MCP нужно внедрять осознанно, потому что каждый сервер добавляет не только возможности, но и контекстную нагрузку.

Что такое MCP и зачем он вообще нужен

Model Context Protocol, или MCP, это открытый стандарт для подключения AI-приложений к внешним системам. В терминах практической разработки это означает, что агент может получать инструменты не только из самого OpenCode, но и из внешних источников: удаленных сервисов, локальных процессов, документационных серверов, поисковых систем, платформ вроде Sentry и так далее.

Хорошая интуиция из общей MCP-документации звучит так: MCP для AI-клиентов играет роль, похожую на USB-C для устройств. То есть это стандартный порт подключения внешних возможностей. Вместо того чтобы каждая AI-система изобретала свою интеграцию с каждым сервисом, используется единый протокол взаимодействия.

Когда MCP действительно полезен в OpenCode-проекте

• Нужно подключать внешнюю документацию или knowledge base.
• Нужно анализировать ошибки и инциденты в observability-системе.
• Нужно доставать информацию из удаленных систем, а не только из локального репозитория.
• Нужно дать агенту actions за пределами репозитория, но в контролируемой форме.

Например, MCP особенно уместен, если вы хотите, чтобы OpenCode умел искать актуальную документацию библиотек, смотреть ошибки в Sentry, искать похожий код по GitHub-примерам или работать с внутренними системами компании через совместимый MCP server.

Главное ограничение: MCP расходует контекст

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

Особенно осторожно нужно быть с серверами, которые тянут большие схемы инструментов или возвращают шумные данные. Поэтому лучший MCP setup — не максималистский, а curated. Подключать стоит только те серверы, которые реально дают выгоду в конкретном проекте.

Как подключаются MCP-серверы в OpenCode

OpenCode настраивает MCP через секцию mcp в opencode.json. У каждого сервера должно быть уникальное имя. Дальше агент может ссылаться на него по этому имени, а конфиг определяет тип подключения и параметры.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "name-of-mcp-server": {
      "enabled": true
    }
  }
}

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

Локальный MCP server запускается как локальный процесс. Это удобно, когда интеграция живет рядом с вашей машиной или проектом: например, локальный documentation index, локальный database bridge или тестовый MCP server.

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

Важные параметры здесь: type, command, environment, enabled и timeout. По сути, вы говорите OpenCode, как запустить локальный MCP server и с каким окружением.

Удаленные MCP-серверы

Удаленный MCP server подключается по URL. Это полезно для SaaS-интеграций и удаленных сервисов, где сервер MCP уже хостится снаружи.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"
      }
    }
  }
}

Удаленный сервер может использовать обычные HTTP-заголовки, API keys и OAuth. Это делает MCP хорошим способом подключать внешние сервисы без написания кастомных интеграций внутри самого репозитория.

OAuth в OpenCode MCP

Отдельный плюс OpenCode в том, что он умеет автоматически обрабатывать OAuth для удаленных MCP-серверов. Если сервер требует аутентификацию, OpenCode может инициировать OAuth-поток и сохранить токены для дальнейшей работы.

Для многих серверов специальная конфигурация не нужна: достаточно указать удаленный MCP server, и при первой необходимости OpenCode предложит пройти авторизацию. При желании можно заранее задать clientId, clientSecret и scope.

opencode mcp auth my-oauth-server
opencode mcp list
opencode mcp logout my-oauth-server

Это очень удобно для сервисов вроде Sentry или других платформ, где доступ должен проходить через нормальную авторизацию, а не через хардкод токенов в конфиге.

Как управлять MCP так, чтобы не перегружать проект

Необязательно делать каждый MCP-сервер доступным каждому агенту. Напротив, хороший паттерн — отключать MCP глобально и включать их только в нужных агентах. Это снижает контекстный шум и делает orchestration более осмысленным.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "enabled": true
    }
  },
  "tools": {
    "context7*": false
  },
  "agent": {
    "system-analyst": {
      "tools": {
        "context7*": true
      }
    }
  }
}

Такой подход особенно полезен, если MCP нужен только части ролей. Например, analyst- или docs-oriented агентам может понадобиться documentation search, а data-engineer-агенту это будет просто лишним шумом.

Практические MCP-сценарии для OpenCode-проекта

MCP, пользовательские инструменты и skills: как не перепутать

Эти три слоя легко спутать, но роли у них разные:

• MCP подключает внешние системы и внешние инструменты через стандартный протокол.
• Пользовательские инструменты — это ваши собственные JS/TS-инструменты внутри экосистемы OpenCode.
• Skills — это не инструменты, а инструкции и playbooks для мышления и workflow.

Если задачу нужно решать через внешний сервис или внешний источник данных — это обычно MCP. Если нужно просто дать агенту новую внутреннюю функцию, которую вы контролируете кодом, — это custom tool. Если нужно дать способ мышления или набор правил — это skill.