How to Set Up Hermes Agent MCP Server Integration with Tool Filtering

Model Context Protocol (MCP) is an open standard that lets AI agents call tools hosted on external servers. Hermes Agent, the open-source (MIT-licensed) agent from Nous Research, has supported MCP as a client since v0.2.0. Since v0.6.0, it can also run as an MCP server itself, exposing its session data to clients like Claude Desktop and Cursor.

In client mode, which is what this guide focuses on, Hermes discovers MCP servers at startup and registers their tools into the same registry as its built-in tools. From the agent's perspective, an MCP tool works exactly like a native one. The agent calls mcp_github_create_issue the same way it calls terminal or read_file.

The practical value is extensibility without forking the agent. Need GitHub issue management? Add the GitHub MCP server. Need database queries? Add a Postgres MCP server. Need filesystem access scoped to a specific project? Add the filesystem server pointed at that directory. Each server gets its own config block, its own credentials, and its own tool filter.

Tool filtering is where Hermes Agent's MCP support gets interesting compared to a bare MCP client. You can allowlist or blocklist individual tools per server, disable unused MCP primitives (resources and prompts), and set timeouts and sampling policies. This keeps the agent's tool registry lean, reduces token consumption in the context window, and limits the blast radius if a credential gets too much scope.

Hermes Agent installs with a single command on Linux, macOS, WSL2, and Android (Termux):

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

After installation, reload your shell and verify:

source ~/.zshrc   # or ~/.bashrc
hermes doctor

MCP support ships with the standard installation. If you installed an earlier version without it, you can add it manually:

cd ~/.hermes/hermes-agent
uv pip install -e ".[mcp]"

For stdio-based MCP servers (the most common type), you also need the runtime that server expects. Most community MCP servers use Node.js, so make sure npx is on your PATH. Python-based servers typically use uvx. Check the server's README for its runtime requirement.

Finally, pick a model provider. Hermes works with Nous Portal, OpenRouter, OpenAI, NVIDIA NIM, NovitaAI, or your own endpoint:

hermes model

Run hermes or hermes --tui to confirm everything works before touching MCP config.

All MCP configuration lives in ~/.hermes/config.yaml under the mcp_servers key. Each server gets a named block with its connection details.

Stdio servers run as local subprocesses. Hermes starts the process, communicates over stdin/stdout, and kills it on shutdown. This is the default transport and works for most community MCP servers:

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_your_token_here"

HTTP servers run remotely and accept requests over HTTPS. Use this for hosted MCP endpoints or internal APIs:

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer sk_live_xxx"

Each server block supports these configuration keys:

• command and args for stdio servers
• url and headers for HTTP servers
• env for environment variables passed to the server process
• timeout for tool call timeout
• connect_timeout for initial connection timeout
• enabled to toggle a server without deleting its config
• tools for filtering (covered in the next section)
• sampling for LLM inference settings when the server requests completions

After editing config.yaml, you don't need to restart Hermes. Run /reload-mcp in an active chat session and the agent re-discovers all servers and refreshes the tool registry.

A tip on first-time setup: pre-install npm packages before adding them to config. Running npx -y @modelcontextprotocol/server-github once outside Hermes avoids a slow first-launch timeout while npx downloads the package.

Persistent workspaces for your Hermes Agent workflows

Store and share everything your agent produces. 50GB free storage, MCP-ready endpoint, and built-in AI search across all your files. No credit card required.

Sign Up Free

Every MCP server exposes a set of tools, and by default Hermes registers all of them. For a GitHub server, that might include create_issue, list_issues, search_code, create_pull_request, delete_repository, and more. Exposing everything wastes tokens in the agent's context window and increases the chance of the agent calling something destructive.

Tool filtering solves both problems. You configure it in the tools block within each server's config.

Allowlisting restricts the agent to only the tools you specify:

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_your_token_here"
    tools:
      include: [list_issues, create_issue, update_issue, search_code]
      prompts: false
      resources: false

This configuration exposes four GitHub tools and disables the list_prompts, get_prompt, list_resources, and read_resource utility tools that most workflows don't need.

Blocklisting keeps everything except the tools you exclude:

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer sk_live_xxx"
    tools:
      exclude: [delete_customer, refund_payment]
      resources: false

If you specify both include and exclude in the same block, include takes precedence. The blocklist is ignored.

When to use which approach:

• Use allowlists for sensitive systems where you want zero ambiguity about what the agent can touch. Financial APIs, production databases, and customer-facing systems all benefit from explicit tool enumeration.
• Use blocklists when you want broad access but need to carve out a few dangerous operations. A content management API where everything is safe except the delete endpoint is a good candidate.
• Set prompts: false and resources: false on any server where you only need tool calls. This removes four utility tools per server from the registry, which adds up when you have several servers connected.

Tool names in the filter use the server's native names (like create_issue), not the prefixed names Hermes generates internally (like mcp_github_create_issue). Check the server's documentation or ask Hermes "Tell me which MCP-backed tools are available right now" to see the full list.

Hermes Agent ships with over 40 built-in tools covering terminal execution, file editing, web search, image generation, and memory management. MCP tools slot into the same registry, so the agent can chain built-in and external tools in a single workflow without any special orchestration.

For example, an agent could use the built-in web_search tool to research a bug, then use mcp_github_create_issue to file it, then use read_file to check the local codebase for related code. The agent sees all of these as tools in its registry and picks the right one based on the task.

Hermes also has a skills system compatible with the agentskills.io open standard. Skills are on-demand knowledge documents that the agent loads when relevant, following a progressive disclosure pattern that minimizes token usage. There are over 160 tracked skills across 26+ categories, covering everything from DevOps to data analysis.

Skills and MCP tools complement each other. A skill teaches the agent how to approach a problem (the knowledge layer), while MCP tools give it the ability to act (the execution layer). A "deploy to Kubernetes" skill might explain best practices and common pitfalls, while the Kubernetes MCP server provides the actual kubectl operations.

Dynamic tool discovery keeps everything in sync at runtime. When an MCP server's tool list changes, it sends a notifications/tools/list_changed notification, and Hermes automatically re-fetches and updates the registry. No manual /reload-mcp needed for server-side changes.

One configuration pattern worth noting: skills can declare dependencies on specific toolsets using requires_toolsets and fallback_for_toolsets in their manifest. This means a skill can activate automatically when a particular MCP server is connected, or provide a fallback workflow when a server is unavailable.

MCP integration gives Hermes access to external tools, but the outputs from those tools need somewhere to live. Reports generated from GitHub data, files downloaded from APIs, analysis results from database queries: all of it needs persistent storage that survives between sessions and can be shared with humans.

Local filesystem storage works for single-machine setups. Point a filesystem MCP server at a project directory and the agent reads and writes files there directly. But this breaks down when you need to hand files to a colleague, run the agent on a different machine, or coordinate multiple agents working on the same project.

Cloud storage services like S3 or Google Cloud Storage solve the durability problem but don't give you search, AI indexing, or fine-grained sharing controls. You end up building a layer on top to make the files useful.

Fast.io approaches this differently. It provides intelligent workspaces where uploaded files are automatically indexed for semantic search and RAG-powered chat. An agent can upload a GitHub analysis report, and any team member can immediately ask questions about it through the workspace's AI chat, with citations pointing back to specific sections.

For Hermes Agent specifically, Fast.io exposes a MCP server with Streamable HTTP at /mcp and legacy SSE at /sse. This means you can add Fast.io as another MCP server in your Hermes config and give the agent direct access to workspace operations: uploading files, creating shares, querying documents, and managing permissions.

The free agent plan includes 50GB of storage, 5,000 credits per month, 5 workspaces, and 50 shares, with no credit card required and no expiration. That is enough to run a Hermes Agent workflow that generates and stores files across multiple projects.

The ownership transfer feature is particularly relevant for agent workflows. An agent can create an organization, build out workspaces with generated content, and then transfer ownership to a human when the work is ready for review. The agent keeps admin access for ongoing maintenance while the human takes full control of the organization.

Common issues and fixes:

• Tools don't appear after adding a server. Check that the server's runtime is installed (npx, uvx, or python must be on your PATH). Run the server command manually outside Hermes to confirm it starts without errors. Then run /reload-mcp in the chat.
• Fewer tools than expected. This is usually intentional. Review your include/exclude lists and check whether prompts or resources are set to false. Each disabled primitive removes utility tools from the registry.
• Server won't connect. Verify enabled is not set to false. For HTTP servers, confirm the URL is reachable and authentication headers are correct. For stdio servers, check that the command exists and the args are valid.
• Timeout errors on tool calls. Increase the timeout value in the server's config block. Some operations (like searching large repositories) take longer than the default timeout.

Check ~/.hermes/logs/ for MCP-specific debug output. Log entries are tagged with [mcp] for easy filtering.

Security recommendations:

• Use read-only credentials for MCP servers unless write access is explicitly needed. A GitHub token with repo:read scope is safer than one with full repo access when the agent only needs to search code and read issues.
• Scope filesystem MCP servers to specific project directories. Never point one at your home directory or root filesystem.
• Start with allowlists for any server that handles financial data, customer records, or production infrastructure. Expand access incrementally as you build confidence in the agent's behavior.
• Review the sampling configuration if your MCP servers request LLM completions. Sampling is enabled by default, which means an external server can ask Hermes to generate text on its behalf. Set sampling.enabled: false on servers you don't trust with that capability.

Performance tips:

• Fewer registered tools means fewer tokens in the system prompt, which means faster responses and lower costs. Filter aggressively.
• Pre-install npm packages used by stdio servers. The first npx -y invocation downloads the package, which can cause startup timeouts.
• Disable prompts and resources on every server where you only need tool calls. Four fewer tools per server adds up quickly across multiple connections.
• Use /reload-mcp instead of restarting Hermes when testing configuration changes. It is faster and preserves your session context.