Настройка MCP-сервера OpenCode

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

OpenCode поддерживает два типа MCP-серверов:

  • Локальный: процесс MCP, запускаемый через командную строку на вашем компьютере, подходит для локальных инструментов и скриптов.
  • Удалённый: удалённый MCP-сервис, подключаемый через HTTPS, подходит для облачных сервисов и сторонних платформ.

Напоминание о потреблении контекста:Каждый MCP-сервер занимает место в контексте разговора. Чем больше инструментов включено, тем больше токенов расходуется за разговор, и тем легче достичь лимита контекста модели. Рекомендуется включать только те MCP-серверы, которые действительно нужны для текущей задачи, и отключать их после завершения. Некоторые серверы (например, GitHub MCP) имеют большое количество инструментов и потребляют особенно много токенов, поэтому будьте особенно внимательны при их использовании.

Базовая структура конфигурации

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

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-server": {         // 服务器名称（自定义，全局唯一）
      "type": "local",         // 连接类型：local или  remote
      // ...其他配置项
      "enabled": true          // 是否启用，默认为 true
    },
    "another-mcp-server": {    // 可同时配置多个 MCP 服务器
      "type": "remote",
      // ...
    }
  }
}

будетenabledУстановить вfalseможно временно отключить сервер, не удаляя его из файла конфигурации, что позволяет легко включать и отключать его по необходимости:

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-command"],
      "enabled": false          // Временно отключено, конфигурация сохранена; просто измените обратно на true, когда потребуется
    }
  }
}

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

Локальный MCP-сервер предоставляет инструменты, запуская командный процесс на вашей машине. Задайтеtypeв"local", и указать команду запуска черезcommand:

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp-server": {
      "type": "local",                                   // Тип подключения: локальный
      "command": ["npx", "-y", "my-mcp-command"],        // Массив команды запуска:
                                                         // Первый элемент — исполняемый файл,
                                                         // Последующие элементы — аргументы
                                                         // Также можно записать как ["bun", "x", "my-mcp-command"]
      "enabled": true,
      "environment": {                                   // Переменные окружения, внедряемые во время выполнения (необязательно)
        "MY_ENV_VAR": "my_env_var_value"
      }
    }
  }
}

Параметры конфигурации локального сервера

Элемент конфигурации Type Обязательный Описание
type String Да Тип подключения; обязателен для локальных серверов"local"
command Массив Да Команда и аргументы для запуска MCP-сервера, в виде массива, например.["npx", "-y", "my-mcp"]
environment Object нет Переменные окружения, внедряемые при запуске сервера, в виде пар ключ-значение
enabled Boolean нет Включать ли сервер при запуске; по умолчаниюtrue
timeout Number нет Тайм-аут (в миллисекундах) для получения списка инструментов с MCP-сервера; по умолчанию5000(5 секунд)

Пример: добавление тестового MCP-сервера

Ниже приведён пример добавления официального тестового MCP-сервера@modelcontextprotocol/server-everything, который можно использовать для проверки того, правильно ли работает функциональность MCP:

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mcp_everything": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"]
      // npx -y означает автоматическое подтверждение установки; не нужно вручную запускать npm install
    }
  }
}

После завершения настройки добавьте имя сервера в запрос, чтобы LLM мог вызывать инструменты этого MCP:

use the mcp_everything tool to add the number 3 and 4

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

Удалённый сервер MCP подключается к облачным сервисам по HTTPS. Задайтеtypeв"remote", и укажите адрес сервера черезurl:

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",                               // Тип подключения: удалённый
      "url": "https://my-mcp-server.com",             // Адрес удалённого сервера (обязательно)
      "enabled": true,
      "headers": {                                    // HTTP-заголовки, отправляемые с запросами (необязательно)
        "Authorization": "Bearer MY_API_KEY"          // Обычно используется для аутентификации по API-ключу
      }
    }
  }
}

Параметры конфигурации удалённого сервера

Элемент конфигурации Type Обязательный Описание
type String Да Тип подключения; должен быть заполнен для удалённых серверов"remote"
url String Да Полный HTTPS-адрес удалённого MCP-сервера
enabled Boolean нет Включать ли сервер при запуске; по умолчаниюtrue
headers Object нет HTTP-заголовки, отправляемые с каждым запросом; обычно используются для аутентификации по API-ключу
oauth Объект /false нет Конфигурация аутентификации OAuth или установите значениеfalseчтобы отключить автоматическое определение OAuth
timeout Number нет Тайм-аут (в миллисекундах) для получения списка инструментов с MCP-сервера; по умолчанию5000(5 секунд)

Ссылки на переменные окружения

В файле конфигурации,конфиденциальную информацию, такую как ключи API, не следует записывать напрямую в открытом виде. OpenCode поддерживает чтение системных переменных окружения во время выполнения с помощью{env:变量名}синтаксиса:

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"    // Автоматически считывает значение переменной окружения MY_API_KEY во время выполнения
                                                      // Переменную окружения необходимо заранее задать в системе:
                                                      // export MY_API_KEY=your_actual_key
      }
    }
  }
}

Аутентификация OAuth

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

Автоматический процесс аутентификации

Когда сервер требует аутентификацию OAuth, OpenCode автоматически выполняет следующие шаги:

  1. Обнаруживает ответ 401 (Unauthorized) от сервера
  2. Автоматически запускает процесс авторизации OAuth и открывает браузер, чтобы провести вас через вход
  3. Если сервер это поддерживает, автоматически регистрирует приложение с помощью динамической регистрации клиента (RFC 7591)
  4. Безопасно сохраняет полученный токен в~/.local/share/opencode/mcp-auth.jsonСредняя
  5. Последующие запросы автоматически передают токен; повторный вход не требуется

1. Автоматический OAuth (без дополнительной настройки)

Для большинства серверов MCP, поддерживающих OAuth, просто настройтеurlи OpenCode автоматически проведёт вас через аутентификацию при первом использовании:

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp"
      // Дополнительная настройка не требуется; OpenCode автоматически обрабатывает поток OAuth
    }
  }
}

Вы также можете вручную запустить процесс аутентификации (например, чтобы снова войти после истечения срока действия токена):

opencode mcp auth my-oauth-server

2. Предварительно зарегистрированные учётные данные клиента

Если вы уже получили фиксированный client ID и секрет от поставщика услуг, вы можете указать их непосредственно в конфигурации и пропустить шаг динамической регистрации:

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-oauth-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "{env:MY_MCP_CLIENT_ID}",          // Чтение из переменных среды, чтобы избежать раскрытия в открытом виде
        "clientSecret": "{env:MY_MCP_CLIENT_SECRET}",
        "scope": "tools:read tools:execute"             // Запрашиваемые области разрешений; конкретные значения определяются поставщиком услуг
      }
    }
  }
}

3. Отключение OAuth (использование аутентификации по API-ключу)

Если сервер использует API-ключ вместо аутентификации OAuth, вы можете установитьoauthвfalseчтобы отключить автоматическое определение OAuth и использоватьheadersчтобы передать ключ:

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-api-key-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "oauth": false,                                   // Отключить автоматическое обнаружение OAuth
      "headers": {
        "Authorization": "Bearer {env:MY_API_KEY}"     // Использовать аутентификацию по API-ключу напрямую
      }
    }
  }
}

Параметры конфигурации OAuth

Элемент конфигурации Type Описание
oauth Объект /false Объект конфигурации OAuth; установите вfalseчтобы полностью отключить автоматическое обнаружение OAuth
clientId String Идентификатор клиента OAuth. Если не указан, OpenCode попытается выполнить динамическую регистрацию клиента
clientSecret String Секрет клиента OAuth (если требуется сервером авторизации)
scope String Области разрешений, запрашиваемые во время авторизации. Несколько областей разделяются пробелами; конкретные значения определяются поставщиком услуг

Команды управления аутентификацией

OpenCode предоставляет набор инструментов командной строки для управления состоянием аутентификации MCP:

# 对指定 MCP 服务器进行身份验证（会打开浏览器完成 OAuth 授权）
opencode mcp auth my-oauth-server

# 列出所有已配置的 MCP 服务器及其当前认证状态
opencode mcp list

# 删除指定服务器已存储的凭据（下次使用时需要重新登录）
opencode mcp logout my-oauth-server

# 调试指定服务器的连接和 OAuth 流程（显示认证状态、测试连接、执行 OAuth 发现流程）
opencode mcp debug my-oauth-server

# 查看所有支持 OAuth 的服务器的认证状态
opencode mcp auth list

Переопределение удалённой конфигурации по умолчанию

Организации могут предоставлять.well-known/opencodeпредустановленные конфигурации MCP-серверов участникам через эндпоинты. Эти серверы могут быть отключены по умолчанию. Если вам нужно включить один из них, добавьте запись с тем же именем в вашу локальную конфигурацию и установитеenabled: trueчтобы включить его.Локальная конфигурация переопределит удалённые значения по умолчанию：

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jira": {                                         // Соответствует имени сервера в удалённой конфигурации организации
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true                                 // Установите true локально, чтобы переопределить удалённое состояние по умолчанию (отключено)
    }
  }
}

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

После регистрации MCP-сервера его инструменты появляются в服务器名称_工具名称в виде в списке инструментов OpenCode, и ими можно управлятьtoolsчерез поле для единого управления.

1. Глобальное отключение инструментов конкретного MCP

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-foo": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-foo"]
    },
    "my-mcp-bar": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-bar"]
    }
  },
  "tools": {
    "my-mcp-foo": false    // Отключить все инструменты сервера my-mcp-foo (сервер всё ещё запускается, но его инструменты недоступны)
  }
}

2. Пакетное отключение с помощью Glob-шаблонов

Использование подстановочных знаков Glob позволяет сопоставлять и отключать инструменты с нескольких MCP-серверов одновременно:

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp-foo": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-foo"]
    },
    "my-mcp-bar": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command-bar"]
    }
  },
  "tools": {
    "my-mcp*": false    // Glob-шаблон: отключить инструменты всех серверов, имена которых начинаются с my-mcp
  }
}

3. Включение конкретных инструментов MCP для каждого агента

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

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command"],
      "enabled": true         // Сам сервер продолжает работать (иначе агент тоже не сможет его использовать)
    }
  },
  "tools": {
    "my-mcp*": false          // Шаг 1: глобально отключить все инструменты этого MCP, чтобы они были недоступны в диалогах по умолчанию
  },
  "agent": {
    "my-agent": {
      "tools": {
        "my-mcp*": true       // Шаг 2: включить его только в агенте my-agent; другие агенты не затронуты
      }
    }
  }
}

Правила шаблонов Glob

Подстановочный знак Значение Пример
* Соответствует нулю или более произвольным символам my-mcp*matchesmy-mcp_search、my-mcp_listожидание
? Соответствует ровно одному произвольному символу my-mcp?matchesmy-mcpA, но не соответствуетmy-mcpAB
другие символы Соответствует буквально и точно my-mcp-fooСоответствует только серверам с точно идентичными именами

Инструменты MCP-сервера при регистрации получают префикс с именем сервера. Например, инструменты сервераmyserverрегистрируются какmyserver_toolname. Поэтому, чтобы отключить все инструменты сервера, используйте"myserver_*": falseдля точного совпадения.

Примеры конфигурации

Sentry

Добавьте MCP-сервер Sentry, чтобы запрашивать ошибки, проблемы и данные событий проектов Sentry прямо в диалогах:

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sentry": {
      "type": "remote",
      "url": "https://mcp.sentry.dev/mcp",
      "oauth": {}      // Пустой объект включает автоматическую аутентификацию OAuth; OpenCode автоматически обработает весь процесс OAuth.
    }
  }
}

После добавления конфигурации выполните следующую команду, чтобы завершить авторизацию учетной записи (откроется браузер для входа через OAuth):

opencode mcp auth sentry

После завершения аутентификации добавьтеuse sentryв свой промпт, чтобы вызвать инструменты Sentry:

Show me the latest unresolved issues in my project. use sentry

Context7

Добавьте MCP-сервер Context7, чтобы искать различные технические документы в беседах, помогая LLM получать самые свежие и точные API-справочники:

Пример

// Базовая версия (без оптимизации лимитов запросов)
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

Пример

// После регистрации бесплатной учётной записи использование API-ключа даёт более высокие лимиты запросов
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"    // Чтение API-ключа из переменной окружения
                                                        // Нужно задать заранее: export CONTEXT7_API_KEY=your_key
      }
    }
  }
}

Adduse context7к вашему промпту, чтобы вызвать функцию поиска по документам:

Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7

Вы также можете добавить глобальные правила вAGENTS.mdчтобы LLM автоматически использовала Context7, когда ей нужно обратиться к документации, без необходимости указывать это вручную каждый раз:

When you need to search docs, use `context7` tools.

Grep от Vercel

Добавьте MCP-сервер Grep от Vercel, чтобы искать реальные фрагменты кода на GitHub прямо в диалогах, помогая LLM находить правильное использование API и ссылки на реализацию:

Пример

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gh_grep": {           // Сервер с именем gh_grep, на который ссылаются по этому имени в промптах
      "type": "remote",
      "url": "https://mcp.grep.app"
    }
  }
}

Adduse the gh_grep toolв ваш промпт, чтобы искать примеры кода на GitHub:

What's the right way to set a custom domain in an SST Astro component? use the gh_grep tool

Аналогично вы можете задать глобальные правила вAGENTS.mdчтобы LLM автоматически искал примеры кода, когда не уверен в использовании:

If you are unsure how to do something, use `gh_grep` to search code examples from GitHub.
Другие расширения