Hey folks!
I would like to introduce hermes-mcp, a comprehensive elixir implementation of the https://spec.modelcontextprotocol.io/ that we’ve been building and using in production at CloudWalk. MCP enables standardized communication between LLMs and external tools, and we’re excited to share what we’ve built with the community.
current state & protocol support
hermes provides both client and server implementations with full support for the MCP spec:
- draft & 2024-11-05 spec: complete implementation
- 2025-03-26 spec: partial (missing OAuth authentication)
- 2025-06-18 spec: on the roadmap
client architecture
the client supports multiple transport layers:
- STDIO
- SSE (Server-Sent Events)
- WebSocket
- Streamable HTTP
what’s interesting about the architecture is how it leverages OTP patterns. each client runs as a supervised process tree:
Client.Supervisor
├── Client.Base (handles MCP protocol and state management)
└── Transport Process (manages I/O and acts like a bridge between external world and the client process)
you can use it either as a long-running process or spawn one-off clients for specific tasks. the supervision strategy ensures fault tolerance based on the :one_for_all strategy.
server architecture
the server implementation supports:
- STDIO, SSE, and Streamable HTTP transports
- direct integration with Plug/Phoenix applications
- component-based design for tools, prompts, and resources
- low level implementation or higher-level where the library handle most of the requests/notifications
the server supervision tree adapts based on transport type:
Server.Supervisor
├── Session.Supervisor (for HTTP transports)
├── Server.Base (protocol handler)
└── Transport Process
production usage
we’re currently running hermes in production at CloudWalk, powering capabilities for JIM, our financial assistant serving hundreds of thousands of users across Brazil. our setup includes:
- as MCP client: both local and clusterized deployments providing server capabilities to JIM
- as MCP server (in progress): building a clusterized implementation using Horde for JIM to expose capabilities to external clients like Claude Desktop
why elixir for MCP?
Have you thought about how elixir’s concurrency model maps perfectly to MCP’s architecture? each session gets its own supervised process, state management is clean through genservers, and the fault tolerance means a single bad request won’t bring down your integration. plus, with libraries like Horde, we can easily distribute MCP servers across nodes.
looking for community input
some questions we’re exploring:
- what patterns have you found useful for managing stateful connections with external services?
- how are you handling protocol version negotiation in your APIs?
- anyone else working with MCP or similar AI tool protocols?
we’d particularly love feedback on:
- the component-based server design (using use
Hermes.Server.Component) - our approach to transport abstraction and supervision tree architecture
- ideas for the clusterized server implementation and possible edge cases/caveats
The library is available on
Documentation is on hermes_mcp v0.10.3 — Documentation
What challenges are you facing with LLM integration that MCP and maybe hermes-mcp might help solve?
has been very responsive to, and providing answers/fixes/improvements to, inquiries in my own journey/experience/experimentation Hermes in my own project.
