# MCP integrations — borrow tools you already have

> Connect stdio or HTTP MCP servers so Hermes can use GitHub, filesystems, DBs, and internal APIs.

Canonical: https://www.brainyxai.co.za/education/hermes/mcp-integrations
Markdown: https://www.brainyxai.co.za/md/education/hermes/mcp-integrations.md
Course: Hermes Agent Operator Track
Lesson: 8 of 9
Minutes: 16
Author: Brainyx AI

## What you will be able to do

- Add an MCP server block to config.yaml
- Filter tools per server
- Test MCP-backed actions in chat

## Why MCP matters

[MCP (Model Context Protocol)](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) lets Hermes attach **external tool servers** — GitHub, databases, filesystems, browsers, internal APIs — without writing a native Hermes tool first.

You get:

- Local **stdio** servers and remote **HTTP** MCP servers
- Automatic tool discovery at startup
- Per-server **filtering** so only chosen tools are visible

Practical patterns: [Use MCP with Hermes](https://hermes-agent.nousresearch.com/docs/guides/use-mcp-with-hermes).

## Minimal config shape

Example pattern from the docs (adapt paths to your machine):

```yaml
mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
```

Then start Hermes and ask it to exercise the capability (“list files under …”).

## Safety filters

MCP multiplies power. Prefer:

- Read-only servers first
- Narrow filesystem roots (never your entire home directory on a public bot)
- Explicit allowlists of tool names when the server exposes dozens of tools

## Adjacent integrations

- [Nous Portal](https://hermes-agent.nousresearch.com/docs/integrations/nous-portal)
- [AI Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers)
- [ACP editor integration](https://hermes-agent.nousresearch.com/docs/user-guide/features/acp)
- Fallback providers & credential pools (see Integrations section in docs)

Brainyx AI builds MCP into many client stacks — Hermes is a great sandbox to learn the protocol before production wiring.

## MCP lab

1. Add one well-known MCP server (filesystem or GitHub) with a tight scope.
2. Restart Hermes / reload per docs and ask for a tool that only that server provides.
3. Disable or filter one dangerous tool and confirm it no longer appears.

## Checkpoints

- I can add and verify an MCP server
- I filter MCP tools before wide exposure

## stdio and HTTP servers behave differently

MCP servers reach you two ways, and the distinction has operational consequences.

A **stdio** server runs as a local subprocess. It starts and stops with the agent, its credentials come from your local environment, and its access is bounded by your machine. Simple, and the failure modes are local.

An **HTTP** server is a network service, possibly run by someone else, possibly shared. It can be centrally managed and reused, and it introduces network availability, authentication, and the question of who else can reach it.

Start local. Move to HTTP when you need a capability shared across machines or people, and treat that as introducing a dependency you now have to operate.

## Filtering tools per server

Servers commonly expose more tools than you need. A filesystem server may offer read, write, and delete; a repository server may offer everything from reading issues to force-pushing.

Enable per server only the tools your tasks actually require. This is the cheapest control available and the most frequently skipped. It also makes debugging easier — a short tool list means the agent picks correctly more often.

## Trust and credentials

An MCP server you did not write runs with whatever access you grant it, and it sees the arguments the agent passes. That is a supply chain decision, not a configuration detail.

Before adding a third-party server: read what it does, prefer widely-used and inspectable implementations, give it a dedicated credential scoped to the minimum, and never hand it a token that can do more than the task needs. For anything touching customer data, run a server you control.

## Debugging without guessing

MCP failures are usually one of a few things: the server did not start, it started but registered no tools, the tools registered but the agent is not selecting them, or the tool ran and errored.

Work through them in that order. Check the server process, then the tool list the agent sees, then whether tool descriptions are clear enough to be chosen, then the actual error. Rewriting your prompt to fix a server that never started is a common and frustrating detour.

## SA context

Connecting MCP to internal systems — an ERP, an inventory database, an internal API — is where real operational value appears, and where a personal setup quietly becomes business infrastructure.

At that point apply business rules: dedicated service credentials rather than a staff member's login, read-only until a write case is proven, and logging that survives the laptop. If it becomes something the business depends on, it needs to be [built and owned properly](https://www.brainyxai.co.za/services/ai-implementation).

## Mini-FAQ

**Q: Which servers should I add first?**
A: Ones that remove a real daily friction — usually filesystem or repository access. Adding servers speculatively creates noise.

**Q: How is authentication handled?**
A: Per server, typically via environment variables or its own config. Scope each credential to that server's job.

**Q: Can one bad server affect the others?**
A: It can consume the agent's attention and budget, and if you granted it broad access, its blast radius is your problem. Per-server tool filtering limits this.

## Next lesson

Continue to [security and architecture](https://www.brainyxai.co.za/education/hermes/security-and-architecture).

Official reference: https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp

Course hub: https://www.brainyxai.co.za/education/hermes · Previous: https://www.brainyxai.co.za/education/hermes/messaging-gateway · Next: https://www.brainyxai.co.za/education/hermes/security-and-architecture