Hermes Agent tools and integrations

Tools, toolsets, skills, integrations, and MCP are different

Getting this taxonomy right matters practically: enabling a toolset changes what the model can attempt, installing a skill changes what it is told to do, and adding an MCP server changes who else is in the loop.

Built-in tool categories

The documented built-in tools group like this:

• Web: web_search, web_extract.
• Terminal and files: terminal, process, read_file, patch.
• Browser: browser_navigate, browser_snapshot, browser_vision.
• Media: vision_analyze, image_generate, text_to_speech.
• Orchestration: todo, clarify, execute_code, delegate_task.
• Recall: memory, session_search.
• Automation: cronjob.

Those are bundled into toolsets — including web, search, terminal, file, browser, vision, image_gen, skills, tts, todo, memory, session_search, cronjob, code_execution, delegation, messaging, debugging, and safe — plus dynamic mcp-<server> toolsets for each connected MCP server.

Enable them per interface:

For a single session, restrict the surface directly:

Choose an extension by task

Permission and credential requirements

Work through this least-privilege checklist before enabling anything:

• Enable the narrowest toolset that completes the task. Browser and messaging can wait until they are needed.
• Choose the execution backend deliberately. local runs on your machine; container and cloud-sandbox backends treat the sandbox as the boundary and skip the dangerous-command check inside it.
• Scope every credential at the service. A read-only token is a smaller incident than an admin one.
• Do not rely on ambient environment variables. Sandboxes deliberately do not inherit your shell environment; execute_code blocks variables whose names look like secrets, and MCP subprocesses receive only a safe baseline plus what you explicitly declare.
• Filter MCP tools. tools.include and tools.exclude limit which of a server's tools are exposed at all.
• Keep the approval gate on while you are still learning what an extension does.

Connect external services

Two connection patterns cover almost everything.

Credential-based integrations. Put the service key in ~/.hermes/.env and configure the feature that uses it. Documented examples include search and extraction backends, browser automation services, image generation, and text-to-speech.

MCP servers. Declared in config.yaml, over stdio for local processes or HTTP for remote endpoints:

mcp_servers:
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    tools:
      include: [read_file, list_directory]

mcp_servers:
  example-http:
    url: https://mcp.example.com/mcp
    auth: oauth

Tools from a server are registered as mcp_<server>_<tool>, so their origin stays visible in the transcript. hermes mcp browses and installs catalog entries, hermes mcp login <server> completes an OAuth flow, and /reload-mcp refreshes servers inside a session.

Skills and MCP boundaries

These two are the ones most often confused, because both extend what the agent does.

• A skill adds instructions. It is a document; it cannot reach anything by itself. Its risk is content — someone else's procedure entering your agent's context.
• An MCP server adds capability. It is a running process or a remote endpoint with its own credentials. Its risk is access.

Skills live in ~/.hermes/skills/, install through hermes skills install with a security scan, and carry trust levels from built-in through official, trusted registries, and community. Agent-authored skills can be gated with skills.write_approval: true and scanned with skills.guard_agent_created. Project-local skills must be trusted explicitly with hermes skills trust before they load.

Verify tool calls and outputs

Enabling something is not the same as it working. Verify each new extension:

• The tool appears in the session's available tools.
• A task that needs it shows an actual tool call, not a prose answer.
• The returned data matches the source when you check one value by hand.
• The credential has the scope you intended — try an action you expect to be denied and confirm it is.
• For MCP, the tool name carries its mcp_<server>_ prefix, so you can see which server answered.

Route tool/integration failures

Take the failure to the layer that owns it. If a tool never appears, it is a toolset or MCP registration problem. If it appears and errors, it is a credential or permission problem. If it returns wrong data, it is the upstream service. Cross-component diagnosis, including MCP connection failures and sandbox errors, belongs to tool and integration troubleshooting.

Choose a deeper operational guide

• To see which capabilities exist at all before wiring anything up, start from the capability overview.
• To constrain what an enabled extension may do, work through the security guide.