Hermes Agent MCP: Complete Guide to Tool Integration

MCP stands for Model Context Protocol. It is a standard for connecting agents to external tools without writing custom integration code. Hermes Agent has native MCP support built in, which means you can plug in dozens of pre-built integrations (GitHub, Linear, N8N, Figma, Stripe, Slack) and let your agent discover and use them automatically. This guide shows you how MCP works, why it matters for Hermes, and how to set it up for your team.

What is MCP and Why Hermes Makes It Matter

Model Context Protocol solves a specific problem: agents need tools. Claude needs to read files. Your agent needs to query databases. Traditional solutions require you to write wrapper code for each tool, test the API calls, handle errors, and maintain the integrations as tools change their APIs.

MCP flips this. You install an MCP server (a small program that wraps a tool's API), configure it in your agent, and the agent discovers what tools are available at runtime. No custom code. No brittle integrations. When the tool updates, the server maintainer updates it, not you.

Think of it like USB-C. Before USB-C, every device had its own connector. A USB-C hub is the protocol. Plug in a device, the hub knows what it is, and everything works. MCP works the same way for agents and tools.

Hermes Agent's advantage: it has built-in MCP support at the framework level. You do not install a plugin. You do not work around missing features. The agent's event loop natively speaks MCP, discovers tool capabilities, handles OAuth flows, and enforces per-tool security rules. Compare this to agents built on top of LangChain or AutoGPT, where MCP support is bolted on. In Hermes, it is foundational.

Why this matters for your team: MCP reduces the engineering time to give your agent new capabilities from weeks to minutes. It shifts the burden from "maintain our custom integrations" to "pick which pre-built MCP servers we trust." That is a fundamentally different cost structure.

Hermes vs. Claude Code vs. OpenClaw: How MCP Implementation Differs

Multiple agents support MCP now. The question is not whether they do, but how well and with what tradeoffs.

Claude Code (Anthropic's native agent in Claude 3.5 Sonnet) has MCP support. It uses a sampling-based approach: when Claude needs a tool, it sends a request to the MCP server, the server responds, and Claude decides what to do next. This is stateless and works well for one-shot queries. It also means Claude Code runs inside Anthropic's infrastructure, not on your hardware.

OpenClaw (the predecessor to Hermes, also from Nous Research) had partial MCP support. It was added later, not designed in. The codebase is an older fork of Nous Hermes models. If you are running OpenClaw, you can import your agent configuration into Hermes, but you gain MCP improvements: better OAuth handling, native tool filtering, and support for sampling-based workflows.

Hermes Agent (the current framework from Nous Research, open source, 232.1K GitHub stars) was built for MCP from the ground up. The agent runs in a background event loop. It discovers MCP servers on startup. When the agent or a subagent needs a tool, it queries the local MCP registry, finds the right server, calls it, and handles the result without explicit prompt engineering. Tools are not in the LLM's context; they are in the runtime. This means Hermes can handle tens or hundreds of tools without bloating the token count.

The practical difference: Claude Code is stateless (each query is independent, sandboxed). Hermes is stateful (your agent runs continuously, learns from tools, can spawn subagents that share the same tool ecosystem). OpenClaw is the bridge if you are migrating.

For your 10-100 person company: if you want a managed agent in the cloud, use Claude Code. If you want control, customization, and long-lived agents that evolve, Hermes is the pick. MCP is the mechanism that makes that flexibility real.

The MCP Ecosystem: Which Servers Are Production-Ready

Hermes can connect to any MCP server that speaks the protocol. The question is which ones to trust and use.

Nous Research maintains an official MCP catalog. These servers are vetted, documented, and packaged for one-click installation into Hermes. The catalog includes:

GitHub MCP Server -- Query repositories, create issues, post comments, read pull requests, manage workflows. Read-only queries are safe; write operations (creating PRs, pushing commits) require careful scope filtering. Most teams enable read access and keep writes restricted to subagents with explicit tasks.

Linear MCP Server -- Sync Linear issues, create work items, update statuses, extract project context. Useful for agents that need to triage bugs or generate status updates from your issue tracker.

N8N MCP Server -- Trigger N8N workflows, list available automations, check execution history. This is the bridge to your existing automation layer. If you have a database sync or email workflow in N8N, your Hermes agent can invoke it.

Figma MCP Server -- Read design files, extract components, pull design tokens. Less common in ops workflows, but invaluable for design-aware agents or auto-documentation.

Stripe MCP Server -- Query customers, check invoice history, retrieve subscription details, manage billing events. For fintech teams or ops that handle billing, this is essential.

Slack MCP Server -- Post messages, thread replies, search channels, invite users. Enables agents to send real-time notifications or pull context from Slack conversations.

OpenAI and Anthropic MCP Servers -- These are less common (Claude Code does not need an MCP server to call itself), but the option exists. Use if you have complex multi-LLM chains.

Beyond the official catalog, the community has built servers for Postgres, MongoDB, Notion, GitHub Gists, and hundreds of other APIs. GitHub's optional-mcps directory is a good source. The risk: community servers may be unmaintained or have security issues. Nous Research's vetting process means official servers are audited for credential handling and error patterns. A good rule: use official servers for sensitive operations (billing, user data). Use community servers for internal automation where a mistake does not leak secrets.

When you add a server to Hermes, the agent discovers its capabilities at runtime. If the GitHub server has operations for "read PR comments," "create PR," and "close issue," those appear in the agent's tool list. The agent can then decide which to use based on your instructions. This is the "no custom code" part in action.

Configuring Your First MCP Server: Stdio and HTTP

Hermes supports two MCP transport modes: stdio (local processes) and HTTP (remote servers). Each has tradeoffs.

Stdio servers run as child processes on the same machine as Hermes. Configuration is simple:

mcp_servers:
  github:
    type: stdio
    command: python3 -m hermes_mcp_github
    environment:
      GITHUB_TOKEN: ${env.GITHUB_TOKEN}
      GITHUB_OWNER: your-org

The agent starts the GitHub server as a subprocess, passes environment variables (your GitHub token), and communicates via stdin/stdout. This is fast (local IPC) and secure (no network exposure). Tradeoff: the server must run on the same machine as Hermes. If Hermes is in Kubernetes, the server image is part of your Hermes deployment.

HTTP servers run separately (maybe in another container, or a managed service). Configuration example with Linear:

mcp_servers:
  linear:
    type: http
    url: <Linear MCP endpoint URL>
    headers:
      Authorization: Bearer ${env.LINEAR_API_KEY}

Replace <Linear MCP endpoint URL> with Linear's official MCP server endpoint. The agent sends tool requests over HTTPS. This decouples the server from Hermes: you can restart the server without restarting your agent. Tradeoff: HTTP adds latency and complexity (TLS, authentication, retries). Use HTTP when you have a shared MCP server (e.g., Linear's public endpoint) or you are running Hermes on serverless infrastructure where stdio subprocesses are not practical.

OAuth flows come up immediately. Many servers (GitHub, Stripe, Linear) require OAuth tokens, not API keys. Hermes handles this:

1. Agent detects a server that requires OAuth.
2. User opens a browser, authenticates with the service (e.g., GitHub), grants permissions.
3. Token is stored securely in Hermes' credential manager.
4. Server uses the token for subsequent requests.

In a team setting: your team lead configures GitHub's MCP server once, runs the OAuth flow once, and the token is stored. The agent can then use it for all team members. If you have subagents (agents spawned by the main agent), they inherit the parent's credential scope, so you can restrict a subagent to read-only GitHub access.

Common mistakes: Environment variables must be set before Hermes starts. If you set GITHUB_TOKEN=xyz in a .env file but do not load it into the container, the server will not have the token. Test this by running hermes agent logs | grep token -- you will see warnings if a required variable is missing.

Another mistake: forgetting to restart Hermes after changing server configuration. MCP servers are discovered at startup. If you add a new Stripe server to your config but do not restart, Hermes will not see it. There is no hot reload (as of August 2026).

Advanced Patterns: OAuth, Tool Filtering, and Security Boundaries

Once you have basic MCP servers running, the question becomes: how do you scale this safely?

Tool filtering is your security boundary. Hermes supports per-server inclusion and exclusion rules:

mcp_servers:
  github:
    type: stdio
    command: python3 -m hermes_mcp_github
    tools:
      include: ["read_pr", "create_issue", "list_repos"]
      exclude: ["delete_repo", "change_permissions"]

Now the GitHub server exposes hundreds of possible operations, but Hermes only offers the agent access to three safe ones. If the agent tries to delete a repository ("delete_repo"), it will not be available in the tool list. The agent cannot do it, not even by prompt injection, because the tool does not exist from the agent's perspective.

This is crucial for subagent delegation. Say you have a main agent and you spawn a subagent to "handle customer support tickets." You can give the subagent access to Linear (to read issues) and Slack (to post replies) but not to Stripe or GitHub. The subagent's environment is defined by the parent:

subagent_config:
  support_agent:
    mcp_servers:
      linear: { include: ["read_issue", "update_status"] }
      slack: { include: ["post_message"] }

The support subagent can read and update issues, can post to Slack, but cannot charge customers or merge code. This is governance by design, not governance by trust.

Sampling support (an advanced feature) allows an MCP server itself to request LLM completions. Example: you have a custom database MCP server. A query comes in. The server needs to decide: should I fetch 10 rows or 10,000? The server can ask the LLM to sample. This is powerful for cost control (small samples, not full table scans) but requires care: the server code must not be malicious, or it can ask the LLM to leak context.

Hermes mitigates this by running sampling in a sandboxed event loop. The LLM sees only what the server explicitly allows. But the safer pattern: do not use sampling for sensitive queries. Keep sampling to read-only operations like "classify these customer feedback comments."

Credential isolation: each server gets its own credential namespace. If the GitHub server's token is compromised, it does not compromise the Linear token or Stripe key. Hermes stores credentials in an encrypted credential manager (if you are using managed Hermes hosting, this is encrypted at rest and in transit; if you self-host, use a secure credential store like HashiCorp Vault or AWS Secrets Manager).

Practical security rules:

1. Give each subagent the minimum set of servers and tools it needs.
2. Exclude destructive operations (deletes, permission changes) unless absolutely necessary.
3. Use HTTP servers for sensitive operations so you can see request logs.
4. Audit which subagents are running and what servers they access. Log every tool invocation.
5. Rotate OAuth tokens quarterly, especially for high-risk services like Stripe.

Real-World Patterns: When MCP Multiplies Agent Power

Here are concrete scenarios where MCP transforms what your agent can do.

GitHub PR Automation: Your main agent monitors GitHub. A new PR arrives. The agent reads the diff using the GitHub MCP server, extracts what changed, asks a subagent "is this code review compliant?" The subagent can read the PR, but cannot push commits; it can only comment. After review, it posts a comment via GitHub's MCP server. No custom code. No webhook setup. The agent handles it.

Database Backups and Cleanup: You have a Postgres MCP server. Your agent runs on a schedule (say, daily). It connects to Postgres via MCP, checks the size of old tables, and initiates a cleanup job in N8N (via the N8N MCP server). If the cleanup fails, it posts a Slack message (via Slack MCP) alerting your ops team. This is a multi-MCP workflow: Postgres -> N8N -> Slack. Three independent services orchestrated by one agent, no glue code.

Customer Onboarding Workflow: Stripe webhook arrives: new customer signed up. Your agent reads the customer data from Stripe (Stripe MCP server), creates a Linear issue for the onboarding team (Linear MCP server), and posts a welcome message to your team Slack (Slack MCP server). Then it asks a subagent: "Generate an onboarding checklist based on the customer's plan level." The subagent has access to Linear and Slack but not Stripe, so it cannot accidentally query billing data.

LLM Cost Monitoring: Your agent has access to OpenAI (to check token costs) and a custom budget MCP server (your in-house tool). Every hour, it compares actual spending to budget, and if you are on pace to exceed budget, it throttles non-critical requests by adjusting your LLM provider's rate limit. This is continuous governance without human intervention.

Design System Extraction: A design team updates Figma. Your agent reads the changes (Figma MCP server), extracts new components, generates documentation (running a subagent), and commits it to a GitHub repo (GitHub MCP server). Your design system documentation is always in sync with Figma.

The pattern: MCP servers act as bridges. Your agent is the orchestrator. Instead of you maintaining custom integrations, MCP servers do. Instead of you writing glue code, Hermes's tool discovery and routing do. You describe what you want in the agent's instructions, and MCP makes it happen.

Troubleshooting Common MCP Connection Issues

Even with a guide, things break. Here are the most common issues and fixes.

"MCP server not responding": The server process crashed or is not listening. For stdio servers, check logs: hermes agent logs | grep github (assuming the server is named "github"). For HTTP servers, check the server's status endpoint or logs. If you get a timeout, the server is not reachable. Fix: restart the server, or if it is Hermes' fault, restart Hermes.

"Tool not appearing in agent's tool list": You configured the server, but the agent does not see its tools. Most likely cause: the server startup failed silently. Check Hermes logs for errors. Second cause: tool filtering. You set exclude: ["*"] accidentally, which hides all tools. Fix: review your MCP config, verify include is not empty.

"OAuth token expired": The agent ran fine yesterday, now it says "Unauthorized." OAuth tokens have expiry times (usually 1-2 hours). Hermes should refresh them automatically, but if refresh fails, you need to re-authenticate. Fix: run hermes agent auth --server github to re-authenticate. This opens a browser, you grant permissions, and the token is updated.

"Timeout waiting for tool result": The agent called a tool, but waited too long for a response. This can happen if the remote service (GitHub, Stripe, Linear) is slow. By default, Hermes waits 30 seconds. If you have slow integrations, increase the timeout: mcp_servers: github: timeout: 60 (60 seconds). Also: check if the remote service is down. GitHub status page, Linear's status page, Stripe's status page -- if they are degraded, your agent will time out.

"Credential not found" or "GITHUB_TOKEN not set": The server needs an environment variable that is not set. Fix: ensure the variable is in your environment before starting Hermes. For Docker: docker run -e GITHUB_TOKEN=xyz. For Kubernetes: add it to your secret and mount it as an env var.

"Too many open connections" or "connection limit exceeded": If you have many subagents all calling the same HTTP server, you can exhaust the connection pool. Fix: configure connection pooling on the server, or reduce the number of concurrent subagents.

A general rule: if an MCP server is not working, check three things in order:

1. Is the server process running? (stdio: check process; HTTP: check logs or health endpoint)
2. Are credentials set? (echo $GITHUB_TOKEN, verify it is not empty)
3. Is the agent's config correct? (hermes agent config | grep server-name, verify the syntax)

From Evaluation to Production: Managed vs. Self-Hosted

Once you understand MCP and have a working setup, the question is: how do you run this in production?

Two paths: managed hosting (Opsily handles the operations) or self-hosted (Docker, Kubernetes, you maintain it).

Managed Hosting with Opsily: You deploy Hermes Agent to Opsily's platform. We handle the infrastructure, updates, scaling, credential management, and backup. You configure MCP servers via a web UI or API. Your agent runs 24/7, always available, automatically scales if load increases. If a server crashes, we restart it. If an MCP server's token expires, we manage the refresh. Cost: usually $100-500 per month depending on complexity, but you save engineering time. Best for: teams without a dedicated DevOps person, or teams that want to focus on the agent's logic, not the operations.

Opsily's managed Hermes hosting includes: GDPR-compliant data centers (Europe and US), encrypted credential storage, audit logs, automatic backups, and team-based access control. When you add a GitHub server, your token is encrypted in transit and at rest. When you add a Linear server, each team member can have their own credentials or share one. We handle the rotation.

See Opsily's Hermes Agent Hosting page for details and pricing.

Self-Hosted Hermes: You run Hermes in your own infrastructure (Docker, Kubernetes, EC2 instance, whatever). You pull the Hermes image, start a container, configure MCP servers in a YAML file, and manage updates yourself. Cost: the infrastructure (maybe $50-200 per month on EC2, or free if it runs on existing Kubernetes), plus your time.

Self-hosted makes sense if: you have DevOps expertise, you have specific security or compliance requirements (HIPAA, SOC 2), or you want to modify the Hermes codebase. Otherwise, it is overhead.

If you self-host, use Docker: build a Dockerfile that includes Hermes, your MCP servers (as subprocesses), and your config. See Opsily's Hermes Agent Docker guide for a template. For Kubernetes, define a StatefulSet or Deployment, mount your config as a ConfigMap, mount credentials as a Secret, and let Kubernetes handle scaling.

Regardless of self-hosted vs. managed: your MCP config is the same. The only difference is who runs Hermes and handles failures.

Frequently Asked Questions

Is Hermes an MCP server? No, Hermes is an MCP client. It connects to MCP servers. You can run Hermes as an MCP server to expose its agents to Claude Code or other tools, but that is an optional feature. By default, Hermes consumes MCP servers.

How do I add MCP to Hermes agent? Update your Hermes config file to include an mcp_servers block with the server name, type (stdio or HTTP), command or URL, and credentials. Then restart Hermes. The server is auto-discovered.

Can Hermes agent use MCP? Yes, Hermes has native MCP support. It can discover and use any server that speaks the MCP protocol.

Is Hermes Agent free and open source? Yes, Hermes is MIT-licensed and open source. You can fork it, modify it, and run it anywhere. Visit the Nous Research GitHub repository to access Hermes Agent source code.

Is there any open source MCP server? Yes, Nous Research maintains an official catalog of open source MCP servers (GitHub, Linear, N8N, Figma, etc.). The community has built others. Check GitHub's optional-mcps directory and mcp.so for a searchable registry.

Is Hermes Agent run locally? Yes, Hermes can run locally on your laptop, on an EC2 instance, or in Kubernetes. You can also use managed hosting (Opsily) to run it in the cloud without managing infrastructure.

Can I restrict which MCP tools a subagent can use? Yes, use tool filtering in your MCP config. Set include and exclude rules per server to define which operations are available to each subagent.

What if an MCP server is down? Hermes retries by default. If a server is unreachable for more than a few seconds, Hermes returns an error to the agent, and the agent can decide what to do (retry, use a fallback, skip the operation, or notify you).

The Bottom Line

MCP is a protocol that lets your agent use external tools without custom integration code. Hermes Agent supports MCP natively, which means you can plug in GitHub, Linear, N8N, Figma, Stripe, Slack, and dozens of other services, and your agent discovers them automatically. Security is built in: tool filtering lets you restrict what each agent or subagent can do. Deployment is flexible: run self-hosted with Docker, or use managed hosting and let Opsily handle the ops.

If you are evaluating Hermes, MCP support is a differentiator. It reduces the engineering overhead of giving your agent capabilities. Start with one or two servers (GitHub and Linear are good choices), test the integrations, and scale from there. For a managed, production-ready setup, try Opsily's Hermes Agent Hosting.