Advanced Patterns
Building a toy server is one thing; building something production-ready is another. Here are patterns you’ll commonly need.
Authentication
For HTTP servers, you’ll likely want to require an API key or bearer token. Hermes can be configured to send an `Authorization` header with each request. In your server, check that header and reject unauthorized requests with an appropriate JSON-RPC error code.
For stdio, authentication is less relevant because the process runs locally under the same user. But if your server makes outbound calls to external APIs, you’ll need to manage those credentials securely.
Error Handling
The MCP spec defines how errors should be returned. If your tool encounters an exception, catch it and return a JSON-RPC error object with a code and message. Hermes will surface that to the user in a readable way. Avoid crashing the server process – wrap your tool logic in try/except blocks and return meaningful error messages.
Streaming Responses
Some operations produce a stream of data (e.g., reading logs, monitoring). MCP supports notifications from server to client, but Hermes currently expects tools to return a single response. For long-running tasks, consider running them in the background and providing a status tool that the user can poll. Alternatively, break the work into chunks and have Hermes call repeatedly.
Stateful Interactions
While MCP requests are stateless (each call is independent), your server can maintain its own state – for example, caching database connections or accumulating results within a session. Just be aware that Hermes may reuse the same server process across multiple tool calls, so you can keep in-memory caches. However, don’t rely on state persisting across Hermes restarts unless you persist to disk.
Pro Tip
Use Docker to containerize your MCP server and deploy it as a sidecar to your Hermes instance. That keeps dependencies isolated and makes updates easy. You can even run multiple servers in separate containers and connect them all to the same Hermes agent.
Real-World Examples
To give you a sense of what’s possible, here are a few community-built MCP servers that extend Hermes in interesting ways.
GitHub API MCP Server: This server exposes tools like “search_issues”, “get_pull_request”, “create_comment”. Hermes can use it to help with code reviews – automatically fetching PR details, adding comments, or checking issue status without leaving the chat.
Database Query Tool: A server that accepts SQL queries (with safeguards) and returns results as formatted tables. This lets business users ask questions like “What were last month’s sales by region?” and get immediate answers from the data warehouse, with Hermes interpreting the results.
IoT Sensor Reader: For a smart home or lab setup, an MCP server can query temperature sensors, motion detectors, or power monitors. Hermes can then answer questions like “Is the server room temperature within range?” or “Show me today’s energy usage trend.”
These examples illustrate the flexibility: your server can be a thin wrapper around an existing API, or it can contain sophisticated business logic. The only limit is what you can code.
Deploying Your MCP Server
Once you’ve built and tested your server, you’ll want it to run reliably. Here are common deployment options.
Systemd service: On a Linux VM, create a systemd unit file to start your server at boot and restart on failure. This is simple and works well for stdio servers launched by Hermes, or for HTTP servers that need to run continuously.
Docker container: Package your server in a Docker image. This is especially handy if you have dependencies that are messy to install globally. For an HTTP server, you can run the container on the same host as Hermes and link them via Docker networking.
Kubernetes: If you’re already running Hermes in k8s, you can deploy your MCP server as a sidecar container or as a separate microservice. This gives you autoscaling and rolling updates.
Whichever method you choose, make sure the server is secured: use TLS for HTTP, restrict network access if possible, and keep secrets out of the image.
Troubleshooting
Things don’t always go smoothly. Here are common pitfalls and how to fix them.
“Connection refused” when Hermes tries to reach the server: Check that the server is running and listening on the expected port or path. For stdio, ensure the command path is correct and the file is executable. For HTTP, verify the URL and that no firewall blocks the connection.
Tool not showing up in Hermes: The server must properly implement the `tools/list` method and return a JSON array of tool definitions. Check the server logs for errors; a misformed JSON response will cause Hermes to skip the server.
Calls time out: Long-running operations should be structured as async tasks. For HTTP, adjust the server timeout and Hermes client timeout if needed. For stdio, ensure your server doesn’t block the event loop; use async code if possible.
Authentication errors: Verify that Hermes is sending the expected auth headers and that your server validates them correctly. Check for typos in the token.
Schema validation failures: Hermes uses the input schema to generate arguments. If your schema is invalid or too restrictive, argument generation may fail. Use a standard JSON Schema format and test it with an online validator.
Conclusion
Building a custom MCP server is a powerful way to extend Hermes Agent beyond its built-in capabilities. You can integrate with any system, control hardware, and implement domain-specific logic while keeping the Hermes platform agnostic. The protocol is simple enough to implement in an afternoon, yet flexible enough to support sophisticated use cases.
If you’re just getting started with Hermes Agent, make sure to read our complete guide Hermes Agent: Persistent AI for Cross-Platform Automation to understand the platform’s core features and decide whether MCP customization is right for you. For many teams, the combination of Hermes plus a few custom MCP servers delivers the perfect blend of out-of-the-box functionality and tailored automation.
Now go build something – the only limit is your imagination.
Frequently Asked Questions
Frequently Asked Questions About Custom MCP Servers
MCP servers can be written in any language that can handle JSON-RPC over stdio or HTTP. Python is the most common due to available libraries, but Node.js, Go, Rust, and others work just as well. The only requirement is that your server speaks the MCP wire format correctly.
Yes. An MCP server is independent. You can point multiple Hermes agents to the same server URL (for HTTP) or have multiple Hermes processes launch the same stdio server. Just be mindful of rate limits and authentication if you share a server across teams.
Minimal. The stdio transport is just a pipe, usually under a millisecond. HTTP adds network latency, typically a few milliseconds on a local network. The heavy lifting is the LLM inference, not the MCP layer. Most MCP servers add less than 10ms overhead per call, which is negligible.
Use HTTPS with TLS to encrypt traffic. Implement API key or OAuth2 authentication and have Hermes send credentials in the Authorization header. Restrict the server’s network exposure with firewalls or VPN. Also, validate all input arguments to prevent injection attacks.
Check the official MCP GitHub repository, community hubs like the Hermes Agent Discord, and aggregators like MCP Exchange. Many open-source projects provide MCP servers for common tools – you might find one that already suits your needs.
Absolutely. MCP is an open standard, not tied to Hermes. Any AI agent that implements the MCP client can use your server. That means you can write once and use with Hermes, Claude Desktop, or any future MCP-compatible platform.
Plugins are typically platform-specific and often require you to host code on the provider’s platform. MCP is a universal protocol that works across any compliant client and server. You own your server, can run it anywhere, and are not locked into a single AI provider’s ecosystem.