> For the complete documentation index, see [llms.txt](https://cerebral-systems.gitbook.io/cerebral-systems-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cerebral-systems.gitbook.io/cerebral-systems-docs/getting-started-1/agent-integration/hermes.md).

# Hermes

Hermes Agent has native MCP client support, so it can load Warrant's stdio MCP server and treat proposal-backed operations as agent tools.

```mermaid
flowchart LR
  U[User or Hermes gateway] --> H[Hermes agent]
  H -->|mcp_warrant_*| M[Warrant MCP process]
  M -->|POST /v1/actions| W[Warrant]
  W --> R[Policy and approval]
  R --> A[Deployment-side actuator]
  A --> S[External system]
```

Hermes remains responsible for reasoning, memory, channels, and selecting a tool. Warrant becomes authoritative only when that selected tool proposes a side effect.

### Current integration status

This repository includes `tools/warrant_mcp_server.py`, a working stdio MCP example originally shaped for Hermes. It exposes one deploy-oriented proposal tool. It is not a general provider proxy or a catalog of production operations.

There is no Nous MCP catalog entry for Warrant in this repository. Configure the local server explicitly and review its source before use.

### Configure Hermes

Add the server to `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  warrant:
    command: "python"
    args:
      - "/absolute/path/to/warrant/tools/warrant_mcp_server.py"
    env:
      WARRANT_URL: "https://warrant.example.com"
      WARRANT_API_KEY: "<tenant-agent-key>"
      WARRANT_AGENT_ID: "hermes-agent"
      WARRANT_RUN_ID: "hermes-primary"
      WARRANT_TARGET_SYSTEM: "hermes.tool.deploy"
    timeout: 30
    supports_parallel_tool_calls: false
    tools:
      include:
        - request_deploy_action
```

Restart Hermes and confirm it discovers `mcp_warrant_request_deploy_action`. The standard Hermes installation includes MCP support; source installations may need the repository's MCP extra installed.

### Make it the action boundary

For every production system guarded by Warrant:

1. expose only Warrant proposal tools for mutating operations;
2. exclude equivalent mutating tools from other Hermes MCP servers and toolsets;
3. do not give Hermes the provider credential used by the actuator;
4. place that credential in the Warrant deployment only;
5. constrain shell, browser, and HTTP tools that can bypass the guarded route;
6. stop the tool turn on `needs_approval` or `deny`, and poll Warrant after `202`.

Hermes has its own tool filtering and permission features. Those are useful local controls, but a Hermes permission response is not a Warrant approval. Warrant approval must be authenticated by the tenant approver API or hosted owner session.

### Proposal and identity mapping

| Hermes value          | Warrant field                               |
| --------------------- | ------------------------------------------- |
| Stable task/action id | `proposal_id`                               |
| Agent/profile label   | `actor.agent_id` claim                      |
| Session or run label  | `actor.run_id` claim                        |
| MCP tool arguments    | Closed `action.parameters` object           |
| Reviewed operation    | `action.target_system` + `action.operation` |

The Warrant agent key becomes the authoritative `authenticated_principal`. An agent cannot make itself an approver by changing its name, profile, prompt, or proposal.

### Validate the integration

* Hermes lists only the intended Warrant MCP tools for the agent profile.
* The Warrant API key can submit actions but cannot approve them.
* `needs_approval` returns a held result and does not trigger a direct fallback tool.
* The approval record names the authenticated approver principal, not Hermes text.
* Warrant's actuator owns the provider token and records the execution result.
* Production wrappers supply a deterministic `proposal_id` for retries of one logical action; the bundled demo generates a new id per invocation.

### What this does not secure

The MCP connection does not automatically cover Hermes built-in tools, other MCP servers, arbitrary commands, browser actions, outbound HTTP, or delivery channels. Warrant also does not govern model selection, inference spending, prompt injection, or Hermes's host. Any provider credential still reachable through those paths remains a bypass.

Framework references: [Hermes MCP documentation](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp/), [toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools/), and [security model](https://hermes-agent.nousresearch.com/docs/user-guide/security/).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cerebral-systems.gitbook.io/cerebral-systems-docs/getting-started-1/agent-integration/hermes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.