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

Hermes Agent connects to external MCP servers and registers their tools alongside its own built-in toolset. This guide covers the full setup, from adding your first MCP server in config.yaml to filtering which tools the agent can see, choosing between stdio and HTTP transports, and wiring in persistent file storage so your agent's work survives between sessions.

Source: https://fast.io/resources/hermes-agent-mcp-server/
Last reviewed: 2026-05-14

## What MCP Does for Hermes Agent

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.

## Prerequisites and Installation

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

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

After installation, reload your shell and verify:

```bash
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:

```bash
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:

```bash
hermes model
```

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

## How to Add and Configure MCP Servers

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:

```yaml
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:

```yaml
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.

## How to Filter MCP Tools

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:

```yaml
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:

```yaml
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.

## Combining MCP Tools with Built-in Tools and Skills

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](https://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.

## Persistent Storage for Hermes Agent Workflows

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.

[Fastio](https://fast.io) approaches this differently. It provides intelligent workspaces where uploaded files are indexed for semantic search and RAG-powered chat once Intelligence is enabled for the workspace. 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, Fastio exposes a [remote MCP server](/storage-for-agents/) at https://mcp.fast.io/mcp (Streamable HTTP) and legacy SSE at https://mcp.fast.io/sse. This means you can add Fastio 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.

Fastio offers a 14-day Business Trial (card required; see [pricing](/pricing/)). 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.

## Troubleshooting and Best Practices

**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.

## Frequently asked questions

### Does Hermes Agent support MCP?

Yes. Hermes Agent has included a built-in MCP client since v0.2.0, and since v0.6.0 it can also run as an MCP server itself using the `hermes mcp serve` command. In client mode, it discovers MCP servers at startup from the config.yaml file and registers their tools into the agent's normal tool registry.

### How do I add MCP tools to Hermes Agent?

Add an entry under the `mcp_servers` key in `~/.hermes/config.yaml`. For local servers, specify the `command` and `args` fields. For remote servers, use the `url` and `headers` fields. Start Hermes or run `/reload-mcp` in an active session, and the new tools appear in the registry alongside built-in tools.

### Can Hermes Agent use external MCP servers?

Yes. Hermes supports both stdio-based servers (local subprocesses launched via npx, uvx, or python) and HTTP-based servers (remote endpoints accessed over HTTPS). You can connect as many servers as you need, each with its own credentials and tool filters.

### What is MCP tool filtering in Hermes Agent?

Tool filtering lets you control which tools from an MCP server are available to the agent. The `tools.include` field creates an allowlist of specific tools, while `tools.exclude` creates a blocklist. You can also disable MCP utility primitives with `prompts: false` and `resources: false`. This reduces token usage and limits what the agent can do with each connected service.

### How does Hermes Agent handle dynamic tool changes from MCP servers?

When an MCP server sends a `notifications/tools/list_changed` notification, Hermes automatically re-fetches the server's tool list and updates the registry. No manual reload is needed for server-side changes. For config-side changes, use `/reload-mcp` to refresh.

### What is the difference between Hermes Agent MCP client mode and server mode?

Client mode (since v0.2.0) lets Hermes call tools on external MCP servers. Server mode (since v0.6.0, via `hermes mcp serve`) exposes Hermes's own conversations and session data as tools that external clients like Claude Desktop and Cursor can access. This guide focuses on client mode configuration.

### Can I use Fastio as an MCP server with Hermes Agent?

Yes. Fastio exposes a MCP server with Streamable HTTP at /mcp and legacy SSE at /sse. Add it as an HTTP-type MCP server in your Hermes config with your Fastio API key, and the agent gets direct access to workspace operations like file uploads, share creation, document queries, and permission management.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.