website/docs/reference/mcp-config-reference.md

metadata

sidebar_position: 8
title: MCP Config Reference
description: >-
  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:

• MCP (Model Context Protocol)
• Use MCP with Hermes

Root config shape

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

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

    enabled: true
    timeout: 120
    connect_timeout: 60
    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
tools	mapping	both	Filtering and utility-tool policy

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