Connect MCP Servers to Hermes — External Tool Integration
Add external tools to Hermes via Model Context Protocol (MCP) — connect to GitHub, databases, file systems, and custom APIs.
MCP (Model Context Protocol) lets Hermes connect to external tool servers. Instead of building tools into Hermes, you can use any MCP-compatible server — GitHub, databases, file systems, browser automation, or custom APIs. If a tool exists as an MCP server, Hermes can use it.
Managed cloud · API costs included · Skill library · Cancel anytime
Before you start:
- ☑Hermes Agent installed
- ☑npx or uvx available (for running MCP servers)
- ☑API keys for the services you want to connect
Steps
- 1
Choose an MCP server
Find servers at github.com/modelcontextprotocol or build your own
- 2
Add the server to config.yaml
Under mcp_servers:, add a named entry with command and args
- 3
Configure environment variables
Add required env vars (API keys, tokens) under the server's env: key
- 4
Set timeouts (optional)
Add timeout: 120 and connect_timeout: 60 for long-running tools
- 5
Restart Hermes
hermes restart to load the new MCP server
- 6
Verify the tools
Run hermes tools to see the new MCP tools listed
Pro Tips
- 💡Environment variables under env: are the ONLY vars passed to the MCP subprocess — secrets are isolated by default
- 💡Use npx -y @modelcontextprotocol/server-name for official MCP servers
- 💡Filter which tools are exposed with allowed_tools: [tool_name1, tool_name2]
- 💡MCP servers support sampling (server-initiated LLM requests) — configure under sampling: for each server
Troubleshooting
❌ MCP server fails to connect
✅ Check that the command and args are correct. Run the command manually in your terminal to see error output.
❌ Tools from MCP server not appearing
✅ Restart Hermes after adding the server. Check hermes tools to see if the server's tools are registered.
❌ API key not being passed to MCP server
✅ Ensure the env var is listed under the server's env: key in config.yaml. Only explicitly listed vars are passed through.
❌ MCP tool calls timing out
✅ Increase timeout: 180 for the server. Some tools (like browser automation) need longer timeouts.