Build Log: Using the Hermes Agent MCP Catalog for One-Click Tool Integration

TLDR: Hermes Agent ships a curated catalog of Nous-approved MCP servers that you install with hermes mcp install <name> — no YAML editing, no hunting for transport args. The catalog handles GitHub OAuth, Linear OAuth, n8n, filesystem, and more. This build log walks through using the interactive picker, the tool-selection checklist at install time, the manifest trust model, and how to reconfigure tool visibility later.

Why the Catalog Exists

MCP servers are powerful, but finding the right command and args for each one, wrestling with environment variables, and manually editing config.yaml slows you down. The Hermes catalog solves this by packaging each MCP server as a manifest — a declarative recipe that Hermes reads, validates, and executes at install time. The result: hermes mcp install linear is one command, not five steps.

[Source: Hermes MCP docs]

The Interactive Picker

The entry point is hermes mcp with no arguments:

$ hermes mcp

This opens an interactive picker showing every catalog entry and its current status. The display looks like:

n8n          available              Manage and inspect n8n workflows from Hermes
linear       enabled                Linear issue/project management (remote OAuth)
github       installed (disabled)   GitHub repo + PR tools

Each row shows status: available (not yet installed), enabled (installed and active), or installed (disabled) (installed but not loaded). For scripting or CI, use the text-only variant:

$ hermes mcp catalog

This prints the same information without the interactive UI. [Source: Hermes MCP docs]

Installing a Server

Let’s walk through installing the Linear MCP server — an OAuth-protected HTTP server for project management:

$ hermes mcp install linear

Hermes reads the manifest at optional-mcps/linear/manifest.yaml in the hermes-agent repo, then:

1. Clones or prepares the server code.
2. Checks credentials — Linear uses remote OAuth, so Hermes opens a browser for authentication, handling PKCE flow and token exchange.
3. Probes the server to discover available tools.
4. Presents a tool-selection checklist:

Select tools for 'linear' (SPACE toggle, ENTER confirm)
  [x] find_issues       Find issues matching a query
  [x] get_issue         Get a single issue
  [x] create_issue      Create a new issue
  [ ] delete_workspace  Delete a Linear workspace

You toggle individual tools with SPACE and confirm with ENTER. Only checked tools end up in your config as mcp_servers.linear.tools.include. This matters because exposing delete_workspace to an autonomous agent carries real risk. [Source: Hermes MCP docs — Tool Selection]

Under the Hood: The Manifest

Every catalog entry ships a manifest.yaml in the optional-mcps/ directory of the hermes-agent repo. A simplified version looks like:

name: linear
version: "1.0.0"
manifest_version: 1
source: "https://github.com/linear/linear-mcp-server"
transport:
  command: "npx"
  args: ["-y", "@linear/mcp-server"]
auth: oauth
tools:
  default_enabled:
    - find_issues
    - get_issue
    - create_issue

Key fields:

• manifest_version — Hermes checks this against its own capabilities. If the manifest requires a newer Hermes, the picker shows: ⚠ 'linear' requires a newer Hermes and you run hermes update to fix.
• auth: oauth — Hermes handles the full OAuth 2.1 flow (discovery, dynamic client registration, PKCE, token refresh). Cached tokens land at ~/.hermes/mcp-tokens/linear.json with 0o600 permissions.
• tools.default_enabled — The pre-checked selection if the probe fails. [Source: Hermes MCP docs — Manifest Version]

Runtime $ENV_VAR Substitution

Manifests can reference environment variables in their transport fields. When Hermes connects to the server at startup, ${VAR} placeholders are resolved from the environment (including ~/.hermes/.env):

transport:
  command: "npx"
  args: ["-y", "@linear/mcp-server"]
  env:
    LINEAR_API_KEY: "${LINEAR_TOKEN}"

There’s also ${INSTALL_DIR} which is substituted at install-time with the cloned repository path. This is useful for servers you build locally. [Source: Hermes MCP docs — ENV Var]

Reconfiguring Tools Later

Need to adjust which tools are visible after install? No need to reinstall:

$ hermes mcp configure linear

This reopens the same tool-selection checklist with your current choices pre-checked. After confirming, run /reload-mcp inside your Hermes chat session to pick up the changes. [Source: Hermes MCP docs — Configure]

Trust Model Awareness

Installing a catalog entry means Hermes executes whatever the manifest specifies — git clone, bootstrap commands, and the MCP server binary. While all manifests are PR-reviewed by Nous Research before merging, the docs recommend reading the manifest yourself, especially these fields:

source:    — Where the server code comes from
install.bootstrap:    — Pre-install shell commands
transport.command:    — What gets executed

The picker prints the manifest’s source: URL at install time, so you can audit the server before confirming. [Source: Hermes MCP docs — Trust Model]

Updating Catalog Entries

MCPs are never auto-updated. To refresh a server’s manifest and code:

$ hermes mcp install linear

Re-running install preserves your previous tool selection (it checks prior config first). If the manifest version has been bumped, the picker warns you if your Hermes is too old. [Source: Hermes MCP docs — Updating]

Key Takeaway

The one-click catalog is the fastest path from “I want to use Linear with Hermes” to “Linear tools are in my agent’s toolbelt.” No config YAML to write, no transport args to look up, no manual OAuth token plumbing. The manifest system handles the boilerplate, the tool checklist limits the blast radius, and commands like hermes mcp configure let you tighten or loosen visibility without reinstalling.

For developers who maintain internal MCP servers, the catalog also shows the pattern: a manifest, an OAuth flow or API key, and a transport definition. Open a PR to optional-mcps/ and anyone with Hermes gets your server in one command.

📖 Related Reads

• ToolBrain — tool reviews, LLM comparisons, and AI workflow guides
• NoCode Insider — AI workflow automation with no-code tools, agents, and APIs
• NiteAgent — AI agent development, frameworks, and production patterns

Cross-links automatically generated from Hermes Tutorials.