Wiki · Integrations
Your app via MCP
MCP fails in two typical ways: the agent is handed an entire tool surface at once, or a server is added where an HTTP request would do.
🔌
MCP fails in two typical ways: the agent is handed a company's entire tool surface at once,
or a server is added where a plain HTTP request would do.
Good integration is not “connect everything” but “connect the right thing with the smallest useful
surface” — which is why tools get filtered and timeouts set in the configuration.
When MCP makes sense
| Use MCP | Do not use MCP |
|---|---|
| A tool already exists in MCP form and you do not want to build one | A built-in Hermes tool already does the job (files, terminal, web) |
| You need a clean layer onto a company system, database or internal API | The server exposes a huge surface of dangerous tools you have no time to filter |
| You want fine-grained control over which tools are visible | It is one narrow thing and a small script would be simpler and safer |
Two shapes of a server
# ~/.hermes/config.yaml — local program (stdio)
mcp_servers:
my-app:
command: "python3"
args: ["/opt/mcp/my-app.py"]
env:
DATABASE_URL: "${DATABASE_URL}" # value from the environment, not hardcoded
enabled: true
timeout: 120
tools:
exclude: ["delete_everything"] # do not hand this to the agent
# a remote server over HTTP
mcp_servers:
company-api:
url: "https://api.company.com/mcp"
headers:
Authorization: "Bearer ${COMPANY_TOKEN}" # from .env, never in git
ssl_verify: true
connect_timeout: 60
tools:
include: ["find_customer", "create_invoice"]
| Key | Purpose |
|---|---|
tools.include / tools.exclude | Which tools the agent can see. Start narrow and widen |
timeout, connect_timeout | How long to wait for an answer and for a connection |
lazy: true | The server starts on the first tool call — Hermes boots faster |
ssl_verify | TLS verification; a path to your own CA for internal certificates |
transport: sse | When the server speaks the older SSE protocol instead of Streamable HTTP |
Step by step
1) run the server on its own and confirm it answers (without Hermes)
2) add the configuration to ~/.hermes/config.yaml
3) hermes mcp list # what Hermes sees
4) try one tool on a harmless query ("find customer 123")
5) only then wire it into a scheduled job or a community
Step 1 matters: if the server does not work alone, inside Hermes it looks like an agent bug and you hunt in the wrong place.
Things to watch
| Situation | What to do |
|---|---|
| The agent suddenly got “dumber” or more expensive | The server added dozens of tools and flooded the context — filter with tools.include |
| Secrets in the configuration | Write ${VARIABLE} and keep the value in .env or a vault |
| The server sometimes “disappears” | Raise timeout or keepalive_interval; for remote servers check ssl_verify |
| A dangerous tool is accidentally available | Put it in tools.exclude before something happens |
| The server slows startup | lazy: true — tools are registered from the cached schema |
How we do it
| Integration | Experience |
|---|---|
| The application database | Great for reading and quick queries; writes only with confirmation |
| Error monitoring | Mostly about the right region (de.sentry.io) — the wrong address looks like an outage |
| Library documentation | Useful per library; a global “everything about everything” slows the agent down |