MCP (Model Context Protocol) in Hermes Agent: Connecting External Tool Servers

{ "TITLE": "Hermes Agent MCP Integration Reference", "BODY": "---\n# Hermes Agent MCP Integration Reference\n\nThis document describes how Hermes Agent connects to external tool servers using the Model Context Protocol (MCP). MCP allows the agent to use tools hosted outside Hermes itself, including GitHub, databases, file systems, browser stacks, and internal APIs.\n\n## Overview\n\nMCP support is included in the standard Hermes Agent installation. No additional installation steps are required. The integration enables Hermes to connect to both local stdio servers and remote HTTP MCP servers within the same configuration. At startup, Hermes automatically discovers and registers tools from configured MCP servers, making them available for use like any native Hermes tool.\n\nWhen an MCP server supports resources and prompts, Hermes provides utility wrappers for list_resources, read_resource, list_prompts, and get_prompt. Per-server filtering allows you to expose only specific MCP tools to Hermes.\n\nA curated catalog of Nous-approved MCP servers is available for one-click installation. Catalog entries are stored under optional-mcps/ in the hermes-agent repository. Presence in the catalog indicates Nous approval. There is no community submission tier; entries are added via pull request merge. Manifests are gated by PR review. You should read the manifest before installing, especially the source:, install.bootstrap:, and transport.command: fields.\n\n### When to Use MCP\n\nUse MCP integration when you want Hermes to use a tool that already exists elsewhere without writing a native Hermes tool first. This is appropriate when you need to integrate local stdio servers and remote HTTP MCP servers in the same configuration. Use it when you want automatic tool discovery and registration at startup. Use it when you need utility wrappers for MCP resources and prompts when supported by the server. Use it when you want per-server filtering to expose only specific MCP tools to Hermes.\n\n### Prerequisites\n\n- Standard Hermes Agent installation. MCP support is included.\n- For stdio servers: node and npx must be installed if using npx-based servers.\n- For catalog installs: git must be installed for cloning manifests.\n- For OAuth: Browser access on the machine running Hermes, or the ability to paste a redirect URL.\n- For mTLS: Client certificate and key files in PEM format.\n- For Hermes as an MCP server: A running Hermes gateway with connected platforms is required for send operations.\n\n## Quick Start: Add an MCP Server Manually\n\n1. Ensure MCP support is included. This is standard in any Hermes install. No extra step is needed.\n2. Edit ~/.hermes/config.yaml and add an mcp_servers entry. For stdio servers, specify command and optionally args. For HTTP servers, specify url and optionally headers.\n3. Start Hermes with hermes chat.\n4. Ask Hermes to use the MCP-backed capability. For example, "List the files in /home/user/projects and summarize the repo structure."\n5. Hermes will discover the MCP server's tools and use them like any other tool.\n\n## Install an MCP Server from the Catalog\n\n1. Run hermes mcp for an interactive picker, or hermes mcp catalog for a plain-text list.\n2. Select an entry from the picker and press Enter to install.\n3. If credentials are required (API key, OAuth), follow the prompts. API keys are written to ~/.hermes/.env. OAuth opens a browser on first connection.\n4. After credentials are provided, Hermes probes the server and presents a checklist of tools. Use SPACE to toggle, ENTER to confirm. Only checked tools are included in the configuration.\n5. If the probe fails, the install still succeeds using manifest defaults or no filter. You can re-run hermes mcp configure <name> later to refine the tool selection.\n6. The entry is stored under optional-mcps/ in the hermes-agent repo.\n\nCatalog entries are disabled by default. Install only what you want. MCPs are never auto-updated. Re-run hermes mcp install <name> to refresh after a Hermes update if the manifest version changed.\n\n### Update Tool Selection for an Installed MCP Server\n\n1. Run hermes mcp configure <name>.\n2. The same checklist reopens with the current selection pre-checked.\n3. Toggle tools as desired and confirm with ENTER.\n\n## Configuration Parameters\n\nThe following parameters can be set under mcp_servers.<name> in ~/.hermes/config.yaml.\n\n### Transport Configuration\n\nmcp_servers.<name>.command (Required for stdio servers) - Executable for a stdio MCP server.\n\nmcp_servers.<name>.args (Optional for stdio servers) - Arguments for the stdio server.\n\nmcp_servers.<name>.env (Optional for stdio servers) - Environment variables passed to the stdio server. For stdio servers, Hermes does not pass the full shell environment. Only explicitly configured environment variables plus a safe baseline are provided.\n\nmcp_servers.<name>.url (Required for HTTP servers) - HTTP MCP endpoint URL.\n\nmcp_servers.<name>.headers (Optional for HTTP servers) - HTTP headers for remote servers.\n\n### mTLS Configuration\n\nmcp_servers.<name>.client_cert (Optional for HTTP servers) - Client certificate for mTLS. Can be a combined PEM path, a [cert, key] 2-tuple, or a [cert, key, password] 3-tuple. Paths support ~ expansion. A missing file raises a clear, server-scoped error rather than an opaque TLS handshake failure.\n\nmcp_servers.<name>.client_key (Optional for HTTP servers) - Client private-key PEM path when the key is separate from the certificate.\n\n### Timeout and Lifecycle\n\nmcp_servers.<name>.timeout (Optional) - Tool call timeout in seconds.\n\nmcp_servers.<name>.connect_timeout (Optional) - Initial connection timeout. This also bounds the MCP initialize handshake.\n\nmcp_servers.<name>.idle_timeout_seconds (Optional) - Recycle a stdio server after this many seconds without a tool call. A value of 0 means never recycle, which is the default.\n\nmcp_servers.<name>.max_lifetime_seconds (Optional) - Recycle a stdio server after this total age. A value of 0 means never recycle, which is the default.\n\n### Server Control\n\nmcp_servers.<name>.enabled (Optional, defaults to true) - If false, Hermes skips the server entirely.\n\nmcp_servers.<name>.supports_parallel_tool_calls (Optional, defaults to false) - If true, tools from this server may run concurrently. Only enable this if the tools are safe to run concurrently, meaning there are no read/write race conditions on shared state.\n\n### Tool Filtering\n\nmcp_servers.<name>.tools.include (Optional) - List of tool names (exact or glob) to whitelist. Only these tools are registered.\n\nmcp_servers.<name>.tools.exclude (Optional) - List of tool names (exact or glob) to blacklist. All tools except these are registered.\n\nIf all tools are filtered out, Hermes does not create an empty runtime MCP toolset for that server.\n\nmcp_servers.<name>.tools.resources (Optional, defaults to true) - If false, disables list_resources and read_resource utility wrappers.\n\nmcp_servers.<name>.tools.prompts (Optional, defaults to true) - If false, disables list_prompts and get_prompt utility wrappers.\n\n### OAuth Authentication\n\nmcp_servers.<name>.auth (Optional for HTTP servers) - Set to oauth for OAuth-authenticated HTTP servers.\n\nmcp_servers.<name>.oauth.redirect_port (Optional) - Fixed port for the OAuth callback listener. Useful for proxied callbacks.\n\nmcp_servers.<name>.oauth.redirect_uri (Optional) - Public HTTPS endpoint that forwards to the callback port.\n\nmcp_servers.<name>.oauth.redirect_host (Optional) - Set to localhost to use localhost instead of 127.0.0.1 in the redirect URI. This can bypass WAF restrictions that reject 127.0.0.1 redirect URIs.\n\nmcp_servers.<name>.oauth.client_id (Optional) - Pre-registered OAuth client ID. Required for providers that do not support dynamic client registration, such as Google Drive and Atlassian.\n\nmcp_servers.<name>.oauth.client_secret (Optional) - Pre-registered OAuth client secret.\n\n### Sampling Configuration\n\nmcp_servers.<name>.sampling.enabled (Optional, default: true) - Enable or disable MCP sampling. Sampling allows MCP servers to make LLM inference requests.\n\nmcp_servers.<name>.sampling.model (Optional) - Override model for sampling requests.\n\nmcp_servers.<name>.sampling.max_tokens_cap (Optional, default: 4096) - Maximum tokens per sampling response.\n\nmcp_servers.<name>.sampling.timeout (Optional, default: 30) - Timeout in seconds per sampling request.\n\nmcp_servers.<name>.sampling.max_rpm (Optional, default: 10) - Rate limit: maximum requests per minute.\n\nmcp_servers.<name>.sampling.max_tool_rounds (Optional, default: 5) - Maximum tool-use rounds in sampling loops.\n\nmcp_servers.<name>.sampling.allowed_models (Optional) - Allowlist of model names the server may request. An empty list means any model is allowed.\n\nmcp_servers.<name>.sampling.log_level (Optional, default: info) - Audit log level. Valid values are debug, info, or warning.\n\n### Elicitation Configuration\n\nmcp_servers.<name>.elicitation.enabled (Optional, default: true) - Enable or disable MCP elicitation. Elicitation allows MCP servers to request structured user input mid-tool-call.\n\nmcp_servers.<name>.elicitation.timeout (Optional, default: 300) - Seconds to wait for user response.\n\n## Set Up OAuth-Authenticated HTTP MCP Server\n\n1. In ~/.hermes/config.yaml, add the server with url and auth: oauth.\n2. Optionally set oauth.redirect_port and oauth.redirect_uri for proxied callbacks.\n3. For providers that reject dynamic client registration (e.g., Google Drive, Atlassian), supply client_id and client_secret under the oauth key.\n4. Run hermes mcp login <server> from a fresh terminal. Do not run this from inside a running Hermes session.\n5. Complete the OAuth flow via browser. For remote or headless hosts, use the paste-back method.\n6. Tokens are cached at ~/.hermes/mcp-tokens/<server>.json with 0o600 permissions.\n\nIf the OAuth flow fails with a 403 error, the WAF is likely rejecting the 127.0.0.1 redirect URI. Set oauth.redirect_host: localhost to work around this. If the OAuth flow fails with a 400 Bad Request error, the provider does not support dynamic client registration. Supply client_id and client_secret manually.\n\nIf the OAuth flow appears to succeed but tool calls time out, the token was not actually acquired. The hermes mcp login command now detects this and prompts for manual client setup.\n\nThe config auto-reload race is a known issue. Editing the config from inside a running Hermes session triggers a 30-second timeout, which is insufficient for interactive OAuth. Always use a fresh terminal for hermes mcp login.\n\n## Set Up mTLS for an HTTP MCP Server\n\n1. In ~/.hermes/config.yaml, add client_cert. This can be a combined PEM path, a [cert, key] 2-tuple, or a [cert, key, password] 3-tuple.\n2. Optionally set client_key separately if the key is not combined in the certificate file.\n3. Paths support ~ expansion. A missing file raises a clear, server-scoped error.\n\n## Runtime Features\n\n### Environment Variable Substitution\n\nRuntime ${ENV_VAR} substitution is supported in transport command, args, url, and headers.\n\n### Dynamic Tool Discovery\n\nDynamic tool discovery via the notifications/tools/list_changed notification is supported. Prompt and resource change notifications are received but not yet acted on.\n\n### Config Reload\n\nMCP configuration can be reloaded via the /reload-mcp slash command.\n\n### Parallel Tool Calls\n\nParallel tool calls for MCP servers are supported when explicitly enabled with supports_parallel_tool_calls: true. Only enable this if the tools are safe to run concurrently.\n\n### Recycling Memory-Heavy Stdio Servers\n\nStdio servers that consume significant memory, such as Playwright with a resident Chromium process, can be recycled after idle or lifetime limits. Set idle_timeout_seconds and max_lifetime_seconds to control recycling behavior.\n\n## Run Hermes as an MCP Server\n\nHermes can also act as an MCP server for other MCP clients such as Claude Code, Cursor, and Codex. This mode is stdio-only.\n\n1. Run hermes mcp serve.\n2. Configure the MCP client to point to Hermes. Set command to hermes and args to ['mcp', 'serve'].\n3. The MCP client manages the process lifecycle.\n\nThe following tools are available when Hermes runs as an MCP server:\n\n- conversations_list\n- conversation_get\n- messages_read\n- attachments_fetch\n- events_poll\n- events_wait\n- messages_send\n- channels_list\n- permissions_list_open\n- permissions_respond\n\nEvent polling operates at approximately 200ms intervals using mtime-optimized database polling. There is no Claude/channel push notification protocol yet. Text-only sends are supported through messages_send. No media or attachment sending is available.\n\nThe gateway does NOT need to be running for read operations, but DOES need to be running for send operations.\n\nBuilt-in presets are available for well-known MCP servers, such as Codex CLI. Use hermes mcp add codex --preset codex to configure the Codex CLI preset.\n\n## Examples\n\n### GitHub Server with Minimal Issue-Management Surface\n\nConfigure a GitHub MCP server with only list_issues, create_issue, and update_issue tools enabled. Disable prompts and resources. Use this configuration to ask Hermes: "Show me open issues labeled bug, then draft a new issue for the flaky MCP reconnection behavior."\n\n### Stripe Server with Dangerous Actions Removed\n\nConfigure a Stripe MCP server with exclude set to delete_customer and refund_payment. Use this configuration to ask Hermes: "Look up the last 10 failed payments and summarize common failure reasons."\n\n### Filesystem Server for a Single Project Root\n\nConfigure a filesystem MCP server using command: npx with args: ['@modelcontextprotocol/server-filesystem', '/home/user/my-project']. Use this configuration to ask Hermes: "Inspect the project root and explain the directory layout."\n\n### Codex CLI Preset\n\nRun hermes mcp add codex --preset codex. This writes a configuration equivalent to command: 'codex' with args: ['mcp-server'].\n\n### Figma Remote MCP with OAuth\n\nConfigure a Figma MCP server with url: https://mcp.figma.com/mcp and auth: oauth. Hermes automatically sets oauth.client_name: 'Claude Code' for mcp.figma.com to bypass the DCR allowlist issue.\n\n### Cloudflare API MCP with Glob Exclusion\n\nConfigure a Cloudflare API MCP server with exclude: ['*_radar_*', '*_accounts_dlp_*', '*_zones_web3_*']. This prunes approximately 3300 tools from the toolset.\n\n### Recycling Memory-Heavy Stdio Server (Playwright)\n\nConfigure a Playwright MCP server with idle_timeout_seconds: 900 and max_lifetime_seconds: 86400. This tears down the Chromium resident process after 15 minutes of inactivity or 24 hours of total lifetime.\n\n## Failure Modes\n\n### MCP Server Not Connecting\n\nCheck that MCP dependencies are installed. They are already included in the standard install. Verify node and npx versions if using npx-based servers. Verify the configuration and restart Hermes.\n\n### Tools Not Appearing\n\nTools may not appear for several reasons: the server failed to connect, discovery failed, filter configuration excluded all tools, the utility capability is not supported, or the server is disabled with enabled: false.\n\n### Resource or Prompt Utilities Not Appearing\n\nThe configuration may disallow them, or the server session may not support the capability.\n\n### OAuth Flow Fails with 403\n\nThe WAF is rejecting the 127.0.0.1 redirect URI. Set oauth.redirect_host: localhost to work around this.\n\n### OAuth Flow Fails with 400 Bad Request\n\nThe provider does not support dynamic client registration. Supply client_id and client_secret manually.\n\n### OAuth Flow Appears to Succeed but Tool Calls Time Out\n\nThe token was not actually acquired. The hermes mcp login command now detects this and prompts for manual client setup.\n\n### Config Auto-Reload Race\n\nEditing the config from inside a running Hermes session causes a 30-second timeout. Use a fresh terminal for hermes mcp login.\n\n### Missing client_cert File\n\nRaises a clear, server-scoped error rather than an opaque TLS handshake failure.\n\n## Manifests and Versioning\n\nManifests pin a manifest_version. If a newer version is present than your Hermes understands, the picker shows a warning. Run hermes update to update Hermes. MCPs are never auto-updated. Re-run hermes mcp install <name> to refresh after a Hermes update if the manifest version changed.\n\n## MCP Sampling\n\nMCP sampling allows MCP servers to make LLM inference requests. This feature is enabled by default. You can configure rate limiting, timeouts, model overrides, and model allowlists. Sampling requests are audited at the configured log level.\n\n## MCP Elicitation\n\nMCP elicitation allows MCP servers to request structured user input mid-tool-call. This feature is enabled by default. Only form-mode elicitations are supported. URL-mode elicitations are declined. You can configure the timeout for user response.\n\n## Detailed Configuration Examples\n\n### Full Stdio Server Configuration\n\nyaml\nmcp_servers:\n filesystem:\n command: npx\n args:\n - '@modelcontextprotocol/server-filesystem'\n - '/home/user/my-project'\n env:\n NODE_ENV: production\n timeout: 60\n connect_timeout: 30\n idle_timeout_seconds: 900\n max_lifetime_seconds: 86400\n enabled: true\n supports_parallel_tool_calls: false\n tools:\n include:\n - 'read*'\n - 'write*'\n exclude: []\n resources: true\n prompts: false\n\n\n### Full HTTP Server Configuration with OAuth\n\nyaml\nmcp_servers:\n figma:\n url: https://mcp.figma.com/mcp\n headers:\n X-Custom-Header: value\n auth: oauth\n oauth:\n redirect_port: 8080\n redirect_uri: https://myproxy.example.com/callback\n redirect_host: localhost\n client_id: your-client-id\n client_secret: your-client-secret\n timeout: 120\n connect_timeout: 30\n enabled: true\n supports_parallel_tool_calls: true\n tools:\n include: []\n exclude:\n - 'delete_*'\n resources: false\n prompts: false\n sampling:\n enabled: true\n model: gpt-4\n max_tokens_cap: 2048\n timeout: 60\n max_rpm: 20\n max_tool_rounds: 10\n allowed_models:\n - gpt-4\n - gpt-3.5-turbo\n log_level: info\n elicitation:\n enabled: true\n timeout: 600\n\n\n### Full HTTP Server Configuration with mTLS\n\nyaml\nmcp_servers:\n secure-api:\n url: https://api.example.com/mcp\n client_cert:\n - /home/user/certs/client.crt\n - /home/user/certs/client.key\n - password123\n client_key: /home/user/certs/client.key\n timeout: 30\n connect_timeout: 15\n enabled: true\n tools:\n include: []\n exclude: []\n resources: true\n prompts: true\n\n\n### Minimal Configuration for a Remote Server\n\nyaml\nmcp_servers:\n github:\n url: https://api.github.com/mcp\n timeout: 60\n\n\n### Configuration with Environment Variable Substitution\n\nyaml\nmcp_servers:\n database:\n command: ${DB_MCP_PATH}/server\n args:\n - '--host'\n - '${DB_HOST}'\n - '--port'\n - '${DB_PORT}'\n env:\n DB_USER: ${DB_USER}\n DB_PASSWORD: ${DB_PASSWORD}\n\n\n## Advanced Configuration Scenarios\n\n### Combining Multiple MCP Servers\n\nYou can configure multiple MCP servers in the same mcp_servers block. Each server is independent and its tools are registered separately.\n\nyaml\nmcp_servers:\n filesystem:\n command: npx\n args:\n - '@modelcontextprotocol/server-filesystem'\n - '/home/user/projects'\n github:\n url: https://api.github.com/mcp\n auth: oauth\n database:\n command: /usr/local/bin/db-mcp-server\n args:\n - '--config'\n - '/etc/db-mcp/config.json'\n\n\n### Using Glob Patterns in Tool Filters\n\nGlob patterns in include and exclude support * for any sequence of characters and ? for a single character.\n\nyaml\nmcp_servers:\n cloudflare:\n url: https://api.cloudflare.com/mcp\n tools:\n include:\n - 'list_*'\n - 'get_*'\n exclude:\n - '*_delete'\n - '*_purge'\n\n\n### Disabling All Tools from a Server\n\nIf you want to register a server but not expose any tools, set tools.include to an empty list and tools.exclude to ['*'].\n\nyaml\nmcp_servers:\n disabled-tools:\n command: npx\n args:\n - '@modelcontextprotocol/server-filesystem'\n - '/tmp'\n tools:\n include: []\n exclude:\n - '*'\n\n\n### Configuring Sampling with Model Allowlist\n\nRestrict sampling to specific models and increase rate limits.\n\nyaml\nmcp_servers:\n ai-assistant:\n url: https://ai.example.com/mcp\n sampling:\n enabled: true\n model: gpt-4\n max_tokens_cap: 4096\n timeout: 60\n max_rpm: 30\n max_tool_rounds: 10\n allowed_models:\n - gpt-4\n - gpt-4-turbo\n log_level: debug\n\n\n### Configuring Elicitation with Extended Timeout\n\nAllow up to 10 minutes for user response during elicitation.\n\nyaml\nmcp_servers:\n form-processor:\n url: https://forms.example.com/mcp\n elicitation:\n enabled: true\n timeout: 600\n\n\n## Troubleshooting Guide\n\n### Diagnostic Steps\n\n1. Verify the configuration file syntax with hermes config validate.\n2. Check that the server is reachable. For HTTP servers, use curl or wget to test the endpoint.\n3. For stdio servers, run the command directly in a terminal to verify it starts correctly.\n4. Check Hermes logs for MCP-related errors. Logs are typically at ~/.hermes/logs/.\n5. Use hermes mcp list to see registered servers and their tool counts.\n6. Use hermes mcp status <name> to check the connection status of a specific server.\n\n### Common Error Messages\n\n- MCP server <name> failed to connect: The server is unreachable or the configuration is incorrect.\n- MCP server <name> initialization failed: The server did not complete the MCP handshake.\n- MCP server <name> tool <tool> not found: The tool name in a filter does not match any discovered tool.\n- MCP server <name> timeout: The server did not respond within the configured timeout.\n- MCP server <name> OAuth token expired: The cached token is no longer valid. Re-run hermes mcp login <name>.\n- MCP server <name> client certificate not found: The client_cert path is invalid or the file is missing.\n\n### Performance Considerations\n\n- Stdio servers start on demand and are recycled based on idle_timeout_seconds and max_lifetime_seconds.\n- HTTP servers maintain a persistent connection. Connection pooling is handled by the underlying HTTP client.\n- Tool filtering reduces the number of tools registered, which can improve startup time and reduce memory usage.\n- Parallel tool calls can improve throughput but require careful consideration of shared state.\n- Sampling requests count against the configured max_rpm rate limit. Exceeding the limit results in a delay.\n\n### Security Considerations\n\n- Environment variables in env are passed to stdio servers. Avoid passing sensitive credentials in args or command as they may appear in process listings.\n- OAuth tokens are cached with 0o600 permissions. Protect the ~/.hermes/mcp-tokens/ directory.\n- mTLS certificates should be stored with restricted permissions. Hermes reads them at startup.\n- Tool filtering is a security measure. Use include and exclude to limit the tools available to Hermes.\n- Sampling requests are audited at the configured log_level. Review logs for unexpected inference requests.\n- Elicitation requests are logged. Monitor for unexpected user input requests.\n\n### Upgrading Hermes\n\nWhen upgrading Hermes, MCP servers are not automatically updated. After an upgrade, check if any catalog entries have a newer manifest_version. Re-run hermes mcp install <name> to refresh the configuration. If a manifest version is newer than your Hermes understands, the picker shows a warning. Run hermes update to update Hermes.\n\n### Uninstalling an MCP Server\n\nTo remove an MCP server, delete its entry from ~/.hermes/config.yaml and restart Hermes. To remove a catalog-installed server, also delete the corresponding directory under optional-mcps/ in the hermes-agent repository.\n\n### Resetting OAuth Tokens\n\nIf OAuth tokens become invalid or expired, delete the token file at ~/.hermes/mcp-tokens/<server>.json and re-run hermes mcp login <name>.\n\n### Debugging Tool Discovery\n\nIf tools are not appearing after configuration, check the following:\n\n1. Run hermes mcp list to see registered servers.\n2. Run hermes mcp status <name> to check the connection.\n3. Check the Hermes logs for discovery errors.\n4. Verify that the server supports the MCP protocol version that Hermes uses.\n5. Test the server independently using an MCP client like mcp-cli.\n\n### Handling Server Crashes\n\nIf a stdio server crashes, Hermes attempts to restart it on the next tool call. If the crash persists, check the server's error output in the Hermes logs. For HTTP servers, a crash results in a connection error. The server must be restarted externally.\n\n### Rate Limiting and Backpressure\n\nHermes does not implement backpressure for MCP tool calls. If a server is overwhelmed, tool calls may time out. Configure timeout and connect_timeout appropriately. For sampling, use max_rpm to limit the request rate.\n\n### Compatibility with MCP Protocol Versions\n\nHermes supports the MCP protocol as implemented by the servers in the catalog. If you use a custom server, ensure it implements the MCP specification correctly. Hermes uses the standard MCP handshake and tool discovery mechanisms.\n\n### Logging and Auditing\n\nHermes logs MCP-related events at the info level by default. Sampling requests are logged at the configured log_level. To increase verbosity, set the HERMES_LOG_LEVEL environment variable to debug. Logs are written to ~/.hermes/logs/hermes.log.\n\n### Backup and Recovery\n\nBack up the following files and directories:\n\n- ~/.hermes/config.yaml - MCP server configurations.\n- ~/.hermes/.env - API keys for catalog-installed servers.\n- ~/.hermes/mcp-tokens/ - OAuth tokens.\n- ~/.hermes/certs/ - mTLS certificates if stored there.\n\nTo recover from a failed upgrade, restore the backup and re-run hermes mcp install <name> for each catalog entry.\n\n### Known Limitations\n\n- Prompt and resource change notifications are received but not acted on.\n- URL-mode elicitations are declined. Only form-mode elicitations are supported.\n- No media or attachment sending is available through messages_send.\n- Event polling operates at approximately 200ms intervals. There is no push notification protocol.\n- The config auto-reload race can cause issues when editing the config from inside a running Hermes session.\n- OAuth flows may fail with providers that do not support dynamic client registration.\n- mTLS certificate paths must be in PEM format. Other formats are not supported.\n- Environment variable substitution is supported in command, args, url, and headers only.\n- Parallel tool calls must be explicitly enabled and are not safe for all tools.\n- Stdio servers do not receive the full shell environment. Only explicitly configured environment variables are passed." }