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

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

Для концептуальных рекомендаций см.:

Корневая структура конфигурации

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

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

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

Ключ	Тип	Применяется к	Значение
`command`	string	stdio	Исполняемый файл для запуска
`args`	list	stdio	Аргументы для подпроцесса
`env`	mapping	stdio	Переменные окружения, передаваемые подпроцессу
`url`	string	HTTP	Удалённая конечная точка MCP
`headers`	mapping	HTTP	Заголовки для запросов к удалённому серверу
`enabled`	bool	оба	Полностью отключить сервер, если `false`
`timeout`	number	оба	Тайм-аут вызова инструмента
`connect_timeout`	number	оба	Тайм-аут первоначального подключения
`tools`	mapping	оба	Политика фильтрации и служебных инструментов
`auth`	string	HTTP	Метод аутентификации. Установите `oauth`, чтобы включить OAuth 2.1 с PKCE
`sampling`	mapping	оба	Политика LLM-запросов, инициируемых сервером (см. руководство по MCP)

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

Ключ	Тип	Значение
`include`	string or list	Белый список нативных серверных инструментов MCP
`exclude`	string or list	Чёрный список нативных серверных инструментов 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 имеет приоритет

Политика utility-инструментов

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

Ресурсы:

list_resources
read_resource

Промпты:

list_prompts
get_prompt

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

tools:
  resources: false

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

tools:
  prompts: false

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

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

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

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

`enabled: false`

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

Поведение:

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

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

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

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

Безопасный allowlist 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

Blacklist 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

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

После изменения конфигурации 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 вызова функций LLM.

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

mcp_my_api_list_items_v2

Помните об этом при написании фильтров include / exclude — используйте исходное имя инструмента MCP (с hyphens/dots), а не санитизированную версию.

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

Для серверов HTTP, которым требуется OAuth, задайте auth: oauth в записи сервера:

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