Connecting MCP Servers to Hermes

What MCP Adds

Lesson 8 covered Hermes’ 60+ built-in tools, general-purpose capabilities that ship with the framework. The Model Context Protocol (MCP) is how you connect everything that doesn’t: GitHub, internal databases, company-specific APIs, third-party SaaS products, and anything your organization already runs as an MCP server, or that you build yourself.

flowchart LR
    MODEL["Model"] --> ORCH["Orchestration layer"]
    ORCH --> BUILTIN["Built-in tools\n(Lesson 8)"]
    ORCH --> MCP1["MCP: GitHub\n(local stdio)"]
    ORCH --> MCP2["MCP: Stripe\n(remote HTTP)"]
    ORCH --> MCP3["MCP: your internal API"]

    style MODEL fill:#EEF0F7,stroke:#6366F1,color:#0F172A
    style ORCH fill:#EEF0F7,stroke:#6366F1,color:#0F172A
    style BUILTIN fill:#f0fdf9,stroke:#0D9488,color:#0F172A
    style MCP1 fill:#f0fdf9,stroke:#0D9488,color:#0F172A
    style MCP2 fill:#f0fdf9,stroke:#0D9488,color:#0F172A
    style MCP3 fill:#f0fdf9,stroke:#0D9488,color:#0F172A

From the model’s point of view, an MCP tool and a built-in tool look identical, both arrive as entries in the <tools> block from Lesson 7.1. The difference is entirely on the implementation side: built-in tools ship inside Hermes; MCP tools run in a separate process or service that Hermes connects to over a standard protocol.

Local Stdio Servers

Most MCP servers run as a local subprocess that Hermes launches and talks to over stdin/stdout. Add one under mcp_servers in config.yaml:

# ~/.hermes/config.yaml
mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
    tools:
      include: [list_issues, create_issue, update_issue, search_code]
    resources: false
    prompts: false

The tools.include list is a filter: even though the GitHub MCP server may expose many more operations, only these four become callable from Hermes. resources: false and prompts: false opt out of the non-tool parts of the MCP spec you’re not using here.

Remote HTTP Servers

Some MCP servers run as hosted HTTP services rather than local subprocesses:

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

Here, tools.exclude is the opposite filter from include: expose everything the server offers except the listed operations. For a payments server, excluding destructive or financially irreversible actions is the kind of decision Module 7 will formalize into a broader guardrails policy, but the mechanism lives here, at the MCP connection layer.

For servers that require full OAuth rather than a static bearer token:

mcp_servers:
  internal-crm:
    url: "https://mcp.internal.corp"
    auth: oauth

Parallel Tool Calls

Some MCP servers can safely handle multiple simultaneous requests. When supports_parallel_tool_calls is enabled for a server, Hermes may execute several of that server’s tools concurrently within a single tool-call batch, rather than one at a time:

mcp_servers:
  internal-search:
    command: "internal-search-mcp"
    supports_parallel_tool_calls: true

Only enable this for servers you know tolerate concurrent requests safely, a server backed by a rate-limited or non-thread-safe API should stay sequential.

Verifying the Connection

hermes doctor          # includes MCP server reachability checks
hermes tools            # confirm the filtered tool list matches what you configured

If a server fails to connect, hermes doctor distinguishes between a launch failure (bad command/args for stdio servers), an auth failure (missing env var or expired OAuth token), and a network failure (unreachable url), which saves you from guessing.

Exercise: connect one MCP server, either a real one relevant to your work or the GitHub server shown above with a read-only personal access token, and scope it down with an include list of no more than three tools. Confirm with hermes tools that only those three appear, not the server’s full catalog.