DemensDeum

Заметки

Language

MCP в OpenCode на DeepSeek: как подключить внешние инструменты

Написано

demensdeum

в

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

OpenCode поддерживает MCP из коробки: и локальные серверы, которые запускаются дочерним процессом, и удалённые, доступные по HTTP. Важный момент — весь MCP-слой реализован на стороне самого OpenCode, а не на стороне провайдера модели. Поэтому DeepSeek получает инструменты MCP как обычные функции в запросе, и ему не нужно ничего знать про сам протокол.

В этой заметке я разберу, как добавить локальный и удалённый сервер, как пройти авторизацию, как не утонуть в токенах и что учитывать при работе с моделями DeepSeek.

Что понадобится

Для работы нужны три вещи:

  • Установленный OpenCode. Если агент ещё не настроен, порядок установки и подключения DeepSeek я разбирал в отдельной заметке.
  • Node.js и npx. Нужны для локальных MCP-серверов, которые распространяются как npm-пакеты.
  • Ключи доступа. Только для тех удалённых серверов, которые требуют авторизации. Публичные серверы вроде Context7 работают и без ключа, но с меньшими лимитами.

Как это устроено

Серверы описываются в конфигурации OpenCode в блоке mcp. У каждого сервера есть уникальное имя, по которому его можно упомянуть в запросе. Инструменты сервера регистрируются с префиксом этого имени, поэтому конфликтов между разными серверами не возникает.

После подключения инструменты MCP становятся доступны модели наравне со встроенными: чтением файлов, правкой кода и запуском команд. С точки зрения DeepSeek это обычные функции, которые агент может вызвать, — именно поэтому связка работает без какой-либо поддержки MCP на стороне API модели.

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

Самый простой способ познакомиться с механизмом — тестовый сервер @modelcontextprotocol/server-everything. Добавим его в файл opencode.json в корне проекта:

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

Поле command — это команда запуска сервера и её аргументы в виде массива. После перезапуска OpenCode инструменты появятся в сессии, и их можно попросить явно:

используй инструмент mcp_everything, чтобы сложить 3 и 4

У локального сервера есть ещё несколько полезных полей. environment задаёт переменные окружения процесса, cwd — рабочую директорию, timeout — таймаут запросов в миллисекундах, а enabled позволяет временно отключить сервер, не удаляя его из конфигурации.

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

Удалённые серверы удобнее: не нужно ничего запускать локально, а доступ к ним идёт по URL. Хороший пример — Context7, который ищет актуальную документацию библиотек. Он подключается без ключа:

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

Если у вас есть бесплатный аккаунт Context7, ключ поднимает лимиты. Заголовки передаются через блок 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:ИМЯ} подставляет значение переменной окружения при загрузке конфигурации, поэтому ключ не попадает в репозиторий. Перед запуском агента переменную нужно экспортировать в терминале.

Ещё один полезный публичный сервер — Grep by Vercel, поиск по примерам кода на GitHub:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gh_grep": {
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

Авторизация через OAuth

Часть удалённых серверов требует OAuth. OpenCode умеет проходить этот сценарий сам: он замечает ответ 401, запускает авторизацию и сохраняет токены. Для Sentry достаточно указать сервер:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}
    }
  }
}

После этого авторизацию можно запустить вручную — откроется браузер:

opencode mcp auth sentry

Служебные команды полезны и в повседневной работе. opencode mcp list показывает серверы и статус авторизации, opencode mcp logout удаляет сохранённые токены, а opencode mcp debug проверяет сетевое подключение и OAuth-обнаружение для конкретного сервера. Токены хранятся локально в файле ~/.local/share/opencode/mcp-auth.json.

Если сервер использует не OAuth, а обычный API-ключ, автоматическую авторизацию стоит отключить, иначе OpenCode будет пытаться пройти OAuth там, где это не нужно:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-api-key-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"
      }
    }
  }
}

Управление инструментами

Инструменты MCP расходуют контекст: каждый сервер добавляет в запрос описания своих функций. Поэтому серверы, которые нужны редко, лучше держать выключенными. Сделать это можно глобально через блок tools:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-foo": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command-foo"]
    },
    "my-mcp-bar": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command-bar"]
    }
  },
  "tools": {
    "my-mcp*": false
  }
}

Шаблон my-mcp* отключает все инструменты, имя которых начинается с этого префикса. Если серверов много, разумнее выключить их глобально и включать точечно для конкретного агента:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": true
    }
  },
  "tools": {
    "my-mcp*": false
  },
  "agent": {
    "my-agent": {
      "tools": {
        "my-mcp*": true
      }
    }
  }
}

Особенности DeepSeek

Связка с DeepSeek работает потому, что модели поддерживают вызов функций, а MCP-инструменты для них выглядят как самые обычные функции. Сам DeepSeek при этом не подключает MCP-серверы и не должен: подключением занимается OpenCode.

На что стоит обратить внимание:

  • Выбор модели. Для рутины и небольших правок достаточно deepseek-flash. Задачи, где нужно удержать в голове много контекста и аккуратно выбрать инструмент, лучше отдавать deepseek-v4-pro.
  • Размер контекста. Тяжёлые серверы вроде GitHub MCP добавляют очень много токенов и вместе с большим проектом легко упираются в лимит. Включайте их только на время конкретной задачи.
  • Стоимость. Схемы инструментов отправляются в каждом запросе, поэтому чем больше серверов включено, тем дороже каждая итерация. Платите вы провайдеру напрямую, так что лишние серверы заметны по счёту.
  • Подсказки агенту. Надёжнее не полагаться на догадливость модели, а прямо называть сервер в запросе или прописать правило в AGENTS.md.

Пример правила для AGENTS.md, чтобы агент сам обращался к нужному источнику:

Когда нужно посмотреть документацию библиотеки, используй инструменты context7.

Практический рецепт

Для повседневной работы обычно хватает двух серверов: Context7 для документации и одного узкого сервера под конкретную задачу — например, Sentry для разбора ошибок или Grep для поиска примеров кода. Остальные лучше держать выключенными и включать по мере необходимости.

Мой порядок действий такой: добавляю сервер в opencode.json, перезапускаю OpenCode, проверяю список через opencode mcp list, затем задаю пробный вопрос с явным упоминанием сервера. Если инструмент не вызывается, смотрю в сторону opencode mcp debug и таймаута — медленный сервер может не успевать ответить за отведённые 30 секунд.

На что обратить внимание

Пара практических моментов. MCP-серверы — это доверенный код: локальный сервер запускается на вашей машине с вашими правами, а удалённому вы отправляете данные запроса. Поэтому ставить случайные серверы из интернета стоит с той же осторожностью, что и любой сторонний CLI.

Ключи и токены держите в переменных окружения и не коммитьте в репозиторий. OAuth-токены OpenCode хранит локально, но на общей машине это тоже стоит учитывать: opencode mcp logout удаляет их, когда доступ больше не нужен.

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

Ссылки

https://opencode.ai/docs/mcp-servers/
https://opencode.ai/docs/config/
https://modelcontextprotocol.io/
https://github.com/upstash/context7
https://mcp.sentry.dev
https://mcp.grep.app
https://github.com/anomalyco/opencode

Источники

https://opencode.ai/docs/mcp-servers/
https://modelcontextprotocol.io/
https://api-docs.deepseek.com/
https://api-docs.deepseek.com/quick_start/agent_integrations/opencode

Комментарии

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *

Больше записей

DemensDeum
Powered by  Соблюдение GDPR Cookie (opens in a new tab)
Обзор конфиденциальности

На этом сайте используются файлы cookie, что позволяет нам обеспечить наилучшее качество обслуживания пользователей. Информация о файлах cookie хранится в вашем браузере и выполняет такие функции, как распознавание вас при возвращении на наш сайт и помощь нашей команде в понимании того, какие разделы сайта вы считаете наиболее интересными и полезными.