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

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

Концептуальные пояснения:

Общая структура конфигурации

mcp_servers:
  <server_name>:
    command: "..."      # stdio-серверы
    args: []
    env: {}

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

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

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

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

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

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

Ключ	Тип	Описание
`include`	string или list	Белый список нативных MCP-инструментов сервера
`exclude`	string или list	Чёрный список нативных MCP-инструментов сервера
`resources`	bool-like	Включить/отключить `list_resources` + `read_resource`
`prompts`	bool-like	Включить/отключить `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 имеет приоритет

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

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

Ресурсы:

list_resources
read_resource

Промпты:

list_prompts
get_prompt

Отключить ресурсы

tools:
  resources: false

Отключить промпты

tools:
  prompts: false

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

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

Это нормальное поведение:

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

`enabled: false`

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

Поведение:

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

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

Если фильтрация исключает все нативные инструменты сервера и вспомогательные инструменты не зарегистрированы, Hermes не создаёт пустой набор инструментов 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"]

  # Пользовательский CA-bundle (частный CA / самоподписанный сервер)
  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_<server>_<tool>

Примеры:

mcp_github_create_issue
mcp_filesystem_read_file
mcp_my_api_query_data

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

mcp_<server>_list_resources
mcp_<server>_read_resource
mcp_<server>_list_prompts
mcp_<server>_get_prompt

Санация имён

Дефисы (-) и точки (.) в именах серверов и инструментов заменяются на подчёркивания перед регистрацией. Это гарантирует, что имена инструментов — допустимые идентификаторы для API function-calling 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