# Quick Start: Hermes MCP

Canonical page: https://www.kuudo.com/docs/quick-start/hermes/

Agent runtimes are where multi-step Amazon work actually finishes. Hand Hermes a goal — audit a catalog and patch the listings that fail validation, build an Amazon Marketing Cloud (AMC) audience and stage it for activation, reconcile a month of Fulfillment by Amazon (FBA) reimbursements — and it plans the work, calls the Amazon tools in order, and returns the artifact. That is the autonomous Amazon operator teams go looking for, running in the agent runtime you chose, against accounts you already own.

Use Hermes Agent's MCP client support when you want Hermes to discover and call tools from your private MCP server.

For the official reference, see [Hermes Agent MCP](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp).

Your MCP server hostname is private to your deployment. It comes from your cloud provider, belongs to your environment, and is not shared across customers. Replace `{your-private-mcp-host}` with the private host shown in your dashboard.

## Before you start

- Install Hermes Agent.
- Confirm MCP support is installed. Standard installs include it, but the Hermes docs show `uv pip install -e ".[mcp]"` when needed.
- Create an API key from the dashboard **Keys** tab.
- Store the key in `MCP_API_KEY` or another local secret source.
- Confirm the private MCP endpoint ends with `/mcp`.

```text
https://{your-private-mcp-host}/mcp
```

## Understand Hermes MCP modes

Hermes supports both directions:

| Mode | What it does |
| --- | --- |
| Hermes as an MCP client | Hermes connects to local stdio servers or remote HTTP MCP servers listed under `mcp_servers`. |
| Hermes as an MCP server | `hermes mcp serve` exposes Hermes messaging capabilities to another MCP client over stdio. |

Use `mcp_servers` when you want Hermes to connect to your existing private MCP server.

## Add the remote MCP server

Store the key in the environment that launches Hermes. You can use `~/.hermes/.env` or your process manager's secret mechanism:

```dotenv
MCP_API_KEY=mcp_live_...
```

Add the server under the top-level `mcp_servers` key in `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  private-mcp:
    url: "https://{your-private-mcp-host}/mcp"
    headers:
      Authorization: "Bearer ${MCP_API_KEY}"
    enabled: true
    timeout: 120
    connect_timeout: 60
```

Hermes reads remote HTTP MCP servers from `url` and `headers`. It discovers MCP tools at startup and registers them into the normal Hermes tool registry.

## Reload Hermes

After saving config, restart Hermes or reload MCP config from a Hermes session:

```text
/reload-mcp
```

If `MCP_API_KEY` is unset in the environment that launches Hermes, the placeholder may remain literal and authentication will fail.

## Tool names and filtering

Hermes prefixes MCP tools to avoid name collisions:

```text
mcp_<server_name>_<tool_name>
```

For a server named `private-mcp`, a tool named `search` is registered as something like:

```text
mcp_private_mcp_search
```

You can limit which tools Hermes exposes from a server:

```yaml
mcp_servers:
  private-mcp:
    url: "https://{your-private-mcp-host}/mcp"
    headers:
      Authorization: "Bearer ${MCP_API_KEY}"
    tools:
      include: [search, fetch]
      resources: false
      prompts: false
```

Use `include` for a small allowlist, `exclude` to hide dangerous tools, and `resources: false` or `prompts: false` when you do not want Hermes to expose MCP resource or prompt utility wrappers for that server.

## Optional parallel tool calls

Hermes runs MCP tools sequentially by default. Only enable parallel execution when the server's tools are safe to run concurrently:

```yaml
mcp_servers:
  private-mcp:
    url: "https://{your-private-mcp-host}/mcp"
    headers:
      Authorization: "Bearer ${MCP_API_KEY}"
    supports_parallel_tool_calls: true
```

Do not enable this for tools that write shared state, mutate records, or depend on strict call order.

## Troubleshooting

### Tools do not appear

Check that Hermes can connect to the server, that discovery succeeds, and that your `tools.include` or `tools.exclude` settings did not filter everything out. If the server is set to `enabled: false`, Hermes skips it entirely.

### Authentication fails

Confirm `MCP_API_KEY` is present in the Hermes process environment. Restart Hermes after changing environment variables.

### Resource or prompt helpers are missing

Hermes only registers resource and prompt utility wrappers when the MCP server supports those capabilities and your config allows them.

### You want Hermes to be the MCP server

That is a different flow. Use:

```bash
hermes mcp serve
```

This starts a stdio MCP server that another MCP client manages. It is not the path for connecting Hermes to your private remote MCP server.

## Related docs

- [MCP Client Configuration](/docs/mcp-client-configuration/)
- [OpenClaw MCP](/docs/quick-start/openclaw/)
- [Codex MCP](/docs/quick-start/codex/)