Choose the Right Boundary for Every Hermes Integration
Hermes connects to model providers, tool servers, browsers, voice systems, IDEs, HTTP clients, memory services, messaging platforms, home automation, and collaboration workspaces. The cleanest architecture uses the boundary already designed for each kind of extension instead of forcing every external system through the same mechanism.[1]
Prefer a native integration when the category already exists
Use built-in configuration when Hermes already owns the lifecycle and user experience. AI providers and routing belong in model configuration; web search backends belong under the web tooling; browser backends belong in browser automation; voice providers belong in TTS or transcription settings; and messaging platforms belong in the gateway. Native paths provide documented capability detection, configuration surfaces, and platform behavior.[1]
The same principle applies to consumption surfaces. ACP embeds Hermes in compatible editors, while the API Server exposes Hermes as an OpenAI-compatible HTTP backend. These are ways to use Hermes, not substitutes for adding a tool integration. Likewise, a messaging adapter changes where conversations arrive; it does not automatically define a reusable external tool contract.[1]
Choose MCP for an external tool server
Model Context Protocol is the right boundary when an external server already exposes tools or should remain independently deployable. Hermes can connect to MCP servers over documented transports, filter tools per server, and register capabilities such as resources and prompts. This makes MCP suitable for GitHub, databases, filesystems, browser stacks, internal APIs, and other services without writing a native Hermes tool.[1]
Keep the MCP boundary narrow. Expose only operations the agent needs, apply server-side authentication and authorization, and use Hermes tool filtering to reduce the visible surface. A standardized protocol does not remove the need for least privilege.
Choose a plugin for Hermes-specific behavior
Plugins extend the Hermes process with custom tools, lifecycle hooks, and CLI commands without modifying core code. They are discovered from the user's Hermes plugin directory, a project-local plugin directory, or installed Python entry points. Choose this route when the extension must participate directly in Hermes lifecycle events, add CLI ergonomics, or package in-process behavior that does not naturally exist as a separate tool server.[1]
A plugin can expose tools, but that does not make it the default for every API. If the service already has a clean MCP server or benefits from language and process isolation, MCP is usually the clearer boundary. If the capability is already native, configure it rather than duplicating it in a plugin.
Make the decision from requirements
Classify the need before selecting technology: model inference, external actions, lifecycle customization, editor embedding, programmatic access, memory, or messaging. Then choose the narrowest official boundary. Credentials, network placement, failure behavior, tool filtering, and deployment ownership should be explicit regardless of the mechanism.
Boundary-selection checklist
- Classify the need as inference, tooling, lifecycle, or access surface.
- Check for an existing native Hermes integration first.
- Use MCP when tools should live in an independent server.
- Use a plugin for Hermes-specific hooks or CLI behavior.
- Limit credentials and exposed operations at the chosen boundary.
- Test the integration in its real deployment surface.
Common pitfalls
- Building a plugin that duplicates a maintained native connector.
- Treating ACP or the API Server as a mechanism for registering external tools.
- Connecting an MCP server and exposing every operation by default.
- Putting provider routing logic inside a tool plugin instead of model configuration.
- Choosing an in-process plugin when isolation and independent deployment are requirements.
Verification
Draw the request path from user surface to Hermes to the external system. Confirm each hop has one clear owner and that no integration is duplicated across native configuration, plugin code, and MCP. For MCP, inspect the filtered tool list and test denied as well as allowed operations. For plugins, verify tool registration, hooks, and CLI behavior without modifying core Hermes code. For native integrations, verify the documented configuration and capability detection on the actual platform.