Справочник конфигурации MCP

Эта страница — компактный справочник, дополняющий основную документацию по MCP.

За концептуальными руководствами обращайтесь к:

• MCP (Протокол контекста модели)
• Использование MCP с VibeOS

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

mcp_servers:
  <имя_сервера>:
    command: "..."      # stdio-серверы
    args: []
    env: {}

    # ИЛИ
    url: "..."          # HTTP-серверы
    headers: {}

    # Дополнительные настройки TLS для HTTP/SSE:
    ssl_verify: true                # bool или путь к связке ЦС (PEM)
    client_cert: "/путь/к/cert.pem"  # клиентский сертификат mTLS (см. ниже)
    # client_key: "/путь/к/key.pem"  # опционально, если ключ в отдельном файле

    enabled: true
    timeout: 120
    connect_timeout: 60
    supports_parallel_tool_calls: false
    tools:
      include: []
      exclude: []
      resources: true
      prompts: true

Ключи сервера

Ключ	Тип	Применяется к	Значение
command	строка	stdio	Исполняемый файл для запуска
args	список	stdio	Аргументы для подпроцесса
env	отображение	stdio	Переменные окружения для подпроцесса
url	строка	HTTP	Конечная точка удалённого MCP
headers	отображение	HTTP	Заголовки для запросов к удалённому серверу
ssl_verify	bool или строка	HTTP	Проверка TLS. true (по умолчанию) использует системные ЦС, false отключает проверку (небезопасно), или строка — путь к пользовательской связке ЦС (PEM)
client_cert	строка или список	HTTP	Клиентский сертификат mTLS. Строка = путь к PEM-файлу, содержащему сертификат + ключ. Список [сертификат, ключ] = отдельные файлы. Список [сертификат, ключ, пароль] = зашифрованный ключ
client_key	строка	HTTP	Путь к закрытому ключу клиента, если client_cert — строка, а ключ находится в отдельном файле
enabled	bool	оба	Полностью пропустить сервер, если false
timeout	число	оба	Тайм-аут вызова инструмента в секундах (по умолчанию: 300)
connect_timeout	число	оба	Тайм-аут начального подключения в секундах (по умолчанию: 60)
supports_parallel_tool_calls	bool	оба	Разрешить параллельный запуск инструментов с этого сервера
tools	отображение	оба	Политика фильтрации и вспомогательных инструментов
auth	строка	HTTP	Метод аутентификации. Установите oauth для включения OAuth 2.1 с PKCE
sampling	отображение	оба	Политика LLM-запросов, инициируемых сервером (см. руководство по MCP)

Ключи политики tools

Ключ	Тип	Значение
include	строка или список	Белый список собственных MCP-инструментов сервера
exclude	строка или список	Чёрный список собственных MCP-инструментов сервера
resources	bool-подобный	Включение/отключение list_resources + read_resource
prompts	bool-подобный	Включение/отключение list_prompts + get_prompt

Семантика фильтрации

include

Если задан include, регистрируются только указанные собственные MCP-инструменты сервера.

tools:
  include: [create_issue, list_issues]

exclude

Если задан exclude, а include — нет, регистрируются все собственные MCP-инструменты сервера, кроме указанных.

tools:
  exclude: [delete_customer]

Приоритет

Если заданы оба параметра, приоритет имеет include.

tools:
  include: [create_issue]
  exclude: [create_issue, delete_issue]

Результат:

• create_issue всё ещё разрешён
• delete_issue игнорируется, так как include имеет приоритет

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

VibeOS может регистрировать следующие вспомогательные обёртки для каждого MCP-сервера:

Ресурсы:

• list_resources
• read_resource

Подсказки:

• list_prompts
• get_prompt

Отключение ресурсов

tools:
  resources: false

Отключение подсказок

tools:
  prompts: false

Регистрация с учётом возможностей

Даже при resources: true или prompts: true VibeOS регистрирует эти вспомогательные инструменты только в том случае, если MCP-сессия действительно предоставляет соответствующую возможность.

Поэтому это нормально:

• вы включаете подсказки
• но вспомогательные инструменты для подсказок не появляются
• потому что сервер не поддерживает подсказки

enabled: false

mcp_servers:
  legacy:
    url: "https://mcp.legacy.internal"
    enabled: false

Поведение:

• попытка подключения не выполняется
• обнаружение не выполняется
• инструменты не регистрируются
• конфигурация остаётся на месте для последующего использования

Поведение при пустом результате

Если фильтрация удаляет все собственные инструменты сервера и не регистрируются вспомогательные инструменты, VibeOS не создаёт пустой набор MCP-инструментов времени выполнения для этого сервера.

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

Безопасный разрешённый список GitHub

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, update_issue, search_code]
      resources: false
      prompts: false

Чёрный список Stripe

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer, refund_payment]

Сервер документации только с ресурсами

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      include: []
      resources: true
      prompts: false

Клиентский сертификат TLS (mTLS)

Для HTTP/SSE-серверов, требующих клиентский сертификат, укажите client_cert (и опционально client_key):

mcp_servers:
  # Объединённый сертификат + ключ в одном PEM-файле
  internal_api:
    url: "https://mcp.internal.example.com/mcp"
    client_cert: "~/secrets/mcp-client.pem"

  # Отдельные файлы сертификата и ключа
  partner_api:
    url: "https://mcp.partner.example.com/mcp"
    client_cert: "~/secrets/client.crt"
    client_key: "~/secrets/client.key"

  # Зашифрованный ключ с парольной фразой (форма списка из 3 элементов)
  bank_api:
    url: "https://mcp.bank.example.com/mcp"
    client_cert: ["~/secrets/client.crt", "~/secrets/client.key", "my-passphrase"]

  # Пользовательская связка ЦС (частный ЦС / самоподписанный сервер)
  lab_api:
    url: "https://mcp.lab.local/mcp"
    ssl_verify: "~/secrets/lab-ca.pem"
    client_cert: "~/secrets/lab-client.pem"

Примечания:

• Пути поддерживают раскрытие ~. Отсутствующие файлы приводят к немедленной ошибке при подключении с сообщением об ошибке в области сервера.
• ssl_verify: false полностью отключает проверку сертификата сервера. Не используйте это с реальными сервисами.
• Работает как с транспортом Streamable HTTP, так и с SSE.

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

После изменения конфигурации MCP перезагрузите серверы с помощью:

/reload-mcp

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

Собственные MCP-инструменты сервера становятся:

mcp_<сервер>_<инструмент>

Примеры:

• mcp_github_create_issue
• mcp_filesystem_read_file
• mcp_my_api_query_data

Вспомогательные инструменты следуют тому же шаблону префикса:

• mcp_<сервер>_list_resources
• mcp_<сервер>_read_resource
• mcp_<сервер>_list_prompts
• mcp_<сервер>_get_prompt

Очистка имени

Дефисы (-) и точки (.) как в именах серверов, так и в именах инструментов заменяются на подчёркивания перед регистрацией. Это гарантирует, что имена инструментов являются допустимыми идентификаторами для API вызова функций LLM.

Например, сервер с именем my-api, предоставляющий инструмент с именем list-items.v2, становится:

mcp_my_api_list_items_v2

Учитывайте это при написании фильтров include / exclude — используйте оригинальное имя MCP-инструмента (с дефисами/точками), а не очищенную версию.

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

Для HTTP-серверов, требующих OAuth, установите auth: oauth в записи сервера:

mcp_servers:
  protected_api:
    url: "https://mcp.example.com/mcp"
    auth: oauth

Поведение:

• VibeOS использует поток OAuth 2.1 PKCE из MCP SDK (обнаружение метаданных, динамическая регистрация клиента, обмен токенами и обновление)
• При первом подключении открывается окно браузера для авторизации
• Токены сохраняются в ~/.vibeos/mcp-tokens/<сервер>.json и повторно используются между сессиями
• Обновление токенов происходит автоматически; повторная авторизация требуется только при сбое обновления
• Применяется только к транспорту HTTP/StreamableHTTP (серверы на основе url)