mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-04-25 00:51:20 +00:00

feat: add supports_parallel_tool_calls for MCP servers

Port from openai/codex#17667: MCP servers can now opt-in to parallel
tool execution by setting supports_parallel_tool_calls: true in their
config. This allows tools from the same server to run concurrently
within a single tool-call batch, matching the behavior already available
for built-in tools like web_search and read_file.

Previously all MCP tools were forced sequential because they weren't in
the _PARALLEL_SAFE_TOOLS set. Now _should_parallelize_tool_batch checks
is_mcp_tool_parallel_safe() which looks up the server's config flag.

Config example:
  mcp_servers:
    docs:
      command: "docs-server"
      supports_parallel_tool_calls: true

Changes:
- tools/mcp_tool.py: Track parallel-safe servers in _parallel_safe_servers
  set, populated during register_mcp_servers(). Add is_mcp_tool_parallel_safe()
  public API.
- run_agent.py: Add _is_mcp_tool_parallel_safe() lazy-import wrapper. Update
  _should_parallelize_tool_batch() to check MCP tools against server config.
- 11 new tests covering the feature end-to-end.
- Updated MCP docs and config reference.

2026-04-14 17:09:50 -07:00

5.8 KiB

Raw Blame History

sidebar_position	title	description
8	MCP Config Reference	Reference for Hermes Agent MCP configuration keys, filtering semantics, and utility-tool policy

MCP Config Reference

This page is the compact reference companion to the main MCP docs.

For conceptual guidance, see:

Root config shape

mcp_servers:
  <server_name>:
    command: "..."      # stdio servers
    args: []
    env: {}

    # OR
    url: "..."          # HTTP servers
    headers: {}

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

Server keys

Key	Type	Applies to	Meaning
`command`	string	stdio	Executable to launch
`args`	list	stdio	Arguments for the subprocess
`env`	mapping	stdio	Environment passed to the subprocess
`url`	string	HTTP	Remote MCP endpoint
`headers`	mapping	HTTP	Headers for remote server requests
`enabled`	bool	both	Skip the server entirely when false
`timeout`	number	both	Tool call timeout
`connect_timeout`	number	both	Initial connection timeout
`supports_parallel_tool_calls`	bool	both	Allow tools from this server to run concurrently
`tools`	mapping	both	Filtering and utility-tool policy
`auth`	string	HTTP	Authentication method. Set to `oauth` to enable OAuth 2.1 with PKCE
`sampling`	mapping	both	Server-initiated LLM request policy (see MCP guide)

`tools` policy keys

Key	Type	Meaning
`include`	string or list	Whitelist server-native MCP tools
`exclude`	string or list	Blacklist server-native MCP tools
`resources`	bool-like	Enable/disable `list_resources` + `read_resource`
`prompts`	bool-like	Enable/disable `list_prompts` + `get_prompt`

Filtering semantics

`include`

If include is set, only those server-native MCP tools are registered.

tools:
  include: [create_issue, list_issues]

`exclude`

If exclude is set and include is not, every server-native MCP tool except those names is registered.

tools:
  exclude: [delete_customer]

Precedence

If both are set, include wins.

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

Result:

create_issue is still allowed
delete_issue is ignored because include takes precedence

Utility-tool policy

Hermes may register these utility wrappers per MCP server:

Resources:

list_resources
read_resource

Prompts:

list_prompts
get_prompt

Disable resources

tools:
  resources: false

Disable prompts

tools:
  prompts: false

Capability-aware registration

Even when resources: true or prompts: true, Hermes only registers those utility tools if the MCP session actually exposes the corresponding capability.

So this is normal:

you enable prompts
but no prompt utilities appear
because the server does not support prompts

`enabled: false`

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

Behavior:

no connection attempt
no discovery
no tool registration
config remains in place for later reuse

Empty result behavior

If filtering removes all server-native tools and no utility tools are registered, Hermes does not create an empty MCP runtime toolset for that server.

Example configs

Safe GitHub allowlist

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 blacklist

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

Resource-only docs server

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

Reloading config

After changing MCP config, reload servers with:

/reload-mcp

Tool naming

Server-native MCP tools become:

mcp_<server>_<tool>

Examples:

mcp_github_create_issue
mcp_filesystem_read_file
mcp_my_api_query_data

Utility tools follow the same prefixing pattern:

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

Name sanitization

Hyphens (-) and dots (.) in both server names and tool names are replaced with underscores before registration. This ensures tool names are valid identifiers for LLM function-calling APIs.

For example, a server named my-api exposing a tool called list-items.v2 becomes:

mcp_my_api_list_items_v2

Keep this in mind when writing include / exclude filters — use the original MCP tool name (with hyphens/dots), not the sanitized version.

OAuth 2.1 authentication

For HTTP servers that require OAuth, set auth: oauth on the server entry:

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