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

String values anywhere in a server entry (env, headers, args, url, …) may reference environment variables with ${VAR} or the Cursor-style SecretRef form ${env:VAR} — both resolve to the same variable, so MCP snippets copied from Cursor / Claude configs work unchanged:

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${env:GITHUB_TOKEN}"   # same as "${GITHUB_TOKEN}"

Values resolve from the active profile's secret scope (falling back to the process environment), so put the secret in ~/.hermes/.env. An unset variable keeps its literal placeholder.

Context variables

Beyond env vars, the Cursor-style context variables are interpolated too (names are case-sensitive):

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"]
    env:
      CACHE_DIR: "${userHome}${/}.cache${/}mcp"

Any other ${...} reference falls through to the env-var lookup above.

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

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

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

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.

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

TLS client certificate (mTLS)

For HTTP/SSE servers that require a client certificate, set client_cert (and optionally client_key):

mcp_servers:
  # Combined cert + key in a single PEM file
  internal_api:
    url: "https://mcp.internal.example.com/mcp"
    client_cert: "~/secrets/mcp-client.pem"

  # Separate cert and key files
  partner_api:
    url: "https://mcp.partner.example.com/mcp"
    client_cert: "~/secrets/client.crt"
    client_key: "~/secrets/client.key"

  # Encrypted key with a passphrase (3-element list form)
  bank_api:
    url: "https://mcp.bank.example.com/mcp"
    client_cert: ["~/secrets/client.crt", "~/secrets/client.key", "my-passphrase"]

  # Custom CA bundle (private CA / self-signed server)
  lab_api:
    url: "https://mcp.lab.local/mcp"
    ssl_verify: "~/secrets/lab-ca.pem"
    client_cert: "~/secrets/lab-client.pem"

Notes:

• Paths support ~ expansion. Missing files fail fast at connect time with a server-scoped error message.
• ssl_verify: false disables server certificate verification entirely. Don't use this with real services.
• Works on both Streamable HTTP and SSE transports.

After changing MCP config, reload servers with:

/reload-mcp

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

The double-underscore delimiter (mcp__…__…) matches the convention used by Claude Code, Codex, and OpenCode, and disambiguates the server/tool boundary even when either component contains underscores.

Name sanitization

Any character that is not a letter, digit, or underscore (hyphens, dots, spaces, etc.) in both server names and tool names is replaced with an underscore 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.

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

Behavior:

• Hermes uses the MCP SDK's OAuth 2.1 PKCE flow (metadata discovery, dynamic client registration, token exchange, and refresh)
• On first connect, a browser window opens for authorization
• Tokens are persisted to ~/.hermes/mcp-tokens/<server>.json and reused across sessions
• Token refresh is automatic; re-authorization only happens when refresh fails
• Only applies to HTTP/StreamableHTTP transport (url-based servers)

MCP vendors and docs can offer a one-click "Add to Hermes" button that opens the Hermes desktop app with a pre-filled server config, mirroring Cursor's cursor://anysphere.cursor-deeplink/mcp/install scheme:

hermes://mcp/install?name=NAME&config=BASE64

• name — the server name. Must match ^[A-Za-z0-9._-]{1,64}$.
• config — the server config object as base64url-encoded JSON (standard base64 is also accepted). The decoded JSON must be an object with either a string url field (http:///https:// only) or a string command field, and may carry any of the server keys documented above. Payloads over 32KB are rejected.

Example (JavaScript):

const config = { url: 'https://mcp.example.com/mcp' }
const link = `hermes://mcp/install?name=example&config=${btoa(JSON.stringify(config))
  .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')}`

Opening the link never installs anything by itself: the desktop app shows a confirmation dialog with the server name and the full pretty-printed config (with an extra caution for command-based servers, which run a local process), and the user must explicitly confirm. Existing server names are never overwritten — the user is asked to rename or cancel.