MCP Servers

Hermes ships with a built-in MCP (Model Context Protocol) client. You can connect it to any MCP server, a database, an API wrapper, a custom tool, and the server's tools appear as first-class Hermes tools, gated by the same toolset and approval system as built-in tools. This lesson covers connecting servers, filtering their tools, and exposing Hermes itself as an MCP server.

What you'll learn

• hermes mcp add connects to stdio or HTTP MCP servers, their tools are auto-discovered and available immediately
• Tool filtering lets you expose only specific tools from a server, keeping the tool list manageable
• hermes mcp serve exposes Hermes as an MCP server, so other tools can call Hermes as a tool

The problem

Hermes has 60+ built-in tools covering files, terminal, web, browser, and more. But every environment has its own tools, an internal API, a database with a specific schema, a deployment pipeline. You could write a Python plugin for each one, or you could connect them through MCP, which is a standard protocol for tool servers that Hermes speaks natively.

Options & when to use each

Connection type	Good for	When to use it
stdio server (local process)	Tools that run on the same machine as Hermes	Local databases, file processors, anything that can be a CLI tool
HTTP server (remote endpoint)	Tools that run on a different machine, or shared services	Team-wide tools, cloud services, APIs you want to centralize
Catalog install (hermes mcp install)	Pre-built MCP servers from the catalog	Quick setup, common integrations

Build it

Step 1: Add an MCP server

Connect your local or remote server to Hermes using the CLI. This integrates external functionality directly into your agent's toolkit.

# stdio server (local process)
hermes mcp add my-db --command "python /path/to/mcp-server.py"

# HTTP server (remote)
hermes mcp add my-api --url "https://mcp.example.com/sse"

Step 2: Verify the connection

Test the link to ensure the server responds properly. This catches bad paths or unreachable endpoints immediately.

hermes mcp test my-db

If the connection succeeds, the server's tools are now available to Hermes. List them:

hermes mcp list

Step 3: Filter tools

A server might expose 20 tools. You only want 3 of them. Use hermes mcp configure to toggle which tools are available:

hermes mcp configure my-db

This opens an interactive selector. Enable only the tools you need. The rest are hidden from Hermes.

Step 4: Expose Hermes as an MCP server

Start the built-in server to allow external tools and agents to leverage Hermes capabilities. This transforms your instance into a functional node for other systems.

hermes mcp serve

This starts an MCP server on the default port. Other MCP clients can now connect to Hermes and use its tools. This is how you make Hermes available as a tool provider to other agents, IDEs, or automation systems.

What goes wrong

Mistake	How you notice it	The fix
stdio server fails to start	hermes mcp test reports connection failure	The command path or Python environment is wrong. Test the command directly in a terminal first: python /path/to/mcp-server.py. If it runs, Hermes should be able to launch it
HTTP server unreachable	Connection timeout	The URL is wrong or the server is down. Verify with curl -I <url>. Check firewall rules if the server is on a different machine
Too many tools from one server	Hermes's tool list becomes unwieldy, model context window balloons	Use hermes mcp configure to filter down to only the tools you actually need. The model doesn't need to see all 20 tools if you only use 3
Server tools appearing in every session	Tools you added for a specific project show up everywhere	MCP servers are global, not per-project. Remove them when you're done: hermes mcp remove my-db

Confirm it worked

Run a dummy local process to ensure the connection and discovery pipeline functions end-to-end. Be sure to remove it afterward to keep your setup clean.

# 1. Add a test MCP server (use a simple one)
hermes mcp add test-server --command "echo '{}'"

# 2. Verify it's listed
hermes mcp list

# 3. Clean up
hermes mcp remove test-server

Next: Desktop Plugins , extending the Desktop app with custom panes, commands, and statusbar widgets.