Hermes Agent connects to external services through MCP, or Model Context Protocol. MCP servers are the bridges between Hermes and the tools, APIs, and services you want it to control. This guide walks you through building a custom MCP server from scratch.
What Is an MCP Server?
An MCP server is a process that exposes tools to AI agents like Hermes and Claude Code. Each tool has a name, description, and input schema. When the agent needs to perform an action, it calls the appropriate MCP tool with the required parameters. The server executes the action and returns the result.
How MCP Fits Into the Hermes Ecosystem
Hermes Agent is designed to be extended. The core agent handles conversation, reasoning, and task execution. MCP servers provide the actual capabilities: accessing databases, calling APIs, managing files, and integrating with any service that has an API. Building a custom MCP server gives Hermes access to your specific tools and services.
Setting Up Your First MCP Server
Choose Your Transport
MCP servers communicate via two transport types: stdio and SSE. Stdio transport runs as a local process and communicates through standard input and output. SSE transport runs as a web server and communicates over HTTP.
For most Hermes Agent deployments, stdio transport is simpler and more secure. The server runs on the same machine as Hermes with no network exposure. SSE transport is better for remote services or when multiple agents need to share the same server.
Define Your First Tool
Every MCP server exposes tools. A tool has three parts: a name, a description, and an input schema. The name is the identifier Hermes uses to call the tool. The description tells Hermes what the tool does and when to use it. The input schema defines what parameters the tool accepts.
Start with one simple tool. A good first tool is a read operation that fetches data from your service. Keep the input schema simple: one or two parameters. Once that works, you can add more complex tools incrementally.
Pro Hint
Write tool descriptions with enough detail that Hermes knows when to use the tool. A vague description like “gets data” is useless. A specific description like “Fetches customer order details by order ID from the e-commerce database. Returns order status, items, total amount, and shipping address” helps Hermes select the right tool for each task.
Writing Tool Handlers
The tool handler is the code that executes when Hermes calls your tool. It receives the input parameters, performs the action, and returns a result.
Handle Errors Gracefully
Every tool handler must handle errors. Network timeouts, invalid inputs, service outages, and permission errors all happen. Your handler should catch these errors and return descriptive error messages that Hermes can relay to the user.
Good error messages tell the user what happened and suggest next steps. Instead of “Error 500,” return “The payment service is currently unavailable. Please try again in 5 minutes or contact support if the issue persists.”
Return Structured Results
Return results in a consistent, structured format. JSON is the standard. Include a status field, the result data, and any relevant metadata. Structured results are easier for Hermes to summarize and present to the user.
Registering Your MCP Server With Hermes
Once your MCP server is running, you need to tell Hermes Agent about it. Add the server configuration to Hermes’s MCP settings. This includes the transport type, the command or URL to connect to, and any credentials required.
Test the Integration
After registering, test the integration by asking Hermes to use your new tool. For a weather API MCP server, ask Hermes about the weather in a specific city. If it calls your tool and returns the result, the integration works.
For debugging, enable verbose logging on both the Hermes Agent side and the MCP server side. This shows exactly what parameters are being passed and what results are being returned.
Best Practices for Production MCP Servers
Moving from a prototype MCP server to production requires attention to several areas.
Rate Limiting and Caching
AI agents can call tools rapidly and in parallel. Implement rate limiting on your MCP server to protect upstream services from abuse. Add caching for frequently requested data to reduce latency and API costs.
Input Validation
Validate all inputs at the MCP server boundary, before they reach your underlying services. Check parameter types, ranges, and formats. Reject invalid inputs with clear error messages that Hermes can act on.
Security Considerations
MCP servers have access to whatever credentials and services they are configured for. Follow security best practices: use least-privilege credentials, restrict network access, validate all inputs, and deploy in isolated environments. For comprehensive security guidance, see our guide on securing MCP servers.
| Aspect | Development Choice | Production Recommendation |
|---|---|---|
| Transport | stdio for simplicity | stdio for local, SSE for remote |
| Tool count | 1-2 to start | Only expose what Hermes needs |
| Error handling | Basic try/catch | Structured errors with user action steps |
| Input validation | Minimal | Strict validation at the boundary |
| Rate limiting | None | Essential for production |
| Deployment | Local dev machine | Sandboxed container or isolated VM |
Extending Your MCP Server
Once your first tool works, you can extend the server with additional tools for related operations. Keep tools focused and composable. A well-designed MCP server has tools that work well individually and combine cleanly for more complex workflows.
For guidance on advanced Hermes Agent patterns like multi-model orchestration and cost optimization, see our guides on Hermes Agent persistent automation and smart multi-model routing strategies.
Frequently Asked Questions
An MCP server is a process that exposes tools to AI agents like Hermes and Claude Code. Each tool has a name, description, and input schema. The agent calls tools to perform actions on external services.
MCP supports stdio (local process communication via stdin/stdout) and SSE (web server communication over HTTP). Stdio is simpler and more secure for local use. SSE is better for remote services or shared multi-agent deployments.
Write tool descriptions with specific details about what the tool does, when to use it, and what it returns. Include parameter descriptions and example usage. The more specific the description, the better Hermes can select and use the right tool.
Return structured error messages that describe what went wrong and suggest next steps. Avoid generic error codes. Instead of ‘Error 500’, say ‘The API service is temporarily unavailable. Please retry in 5 minutes.’
Yes for production. AI agents can call tools rapidly and in parallel. Rate limiting protects upstream services from abuse and prevents unexpected costs from rapid API calls.
Test the tool handlers independently by calling them with sample inputs. Verify they return correct results and handle errors gracefully. Then connect to Hermes and test with natural language requests to verify end-to-end functionality.