Hermes Agent integration

Two ways to connect: the one-click Add to Hermes button, or a YAML block you paste in yourself. Both end at the same place, a respira-wordpress (or per-site respira) entry in that config file.

Connect with one click

Sign in to Respira and open the MCP setup page in your dashboard, then choose Hermes Agent. Selecting Add to Hermes opens a hermes://mcp/install deep link. The desktop app catches it and shows a confirm dialog before writing anything to disk, so nothing installs until you accept it. If you are not signed in yet, respira.press/mcp is the overview of what the server does and which clients it reaches.

This carries every site on your account in one entry, so one approval covers the whole account rather than a single site.

Connect with YAML

No desktop app, or you would rather see the config before it lands on disk? The same dashboard setup page generates the block for copying (choose Hermes Agent, then copy instead of clicking Add to Hermes). Merge it into ~/.hermes/config.yaml under mcp_servers: and keep any servers already listed there.

There are two shapes, and they trade off differently.

stdio, all sites in one entry

This is what the generated block gives you by default:

mcp_servers:
  respira-wordpress:
    command: "npx"
    args:
      - "-y"
      - "@respira/wordpress-mcp-server"
    env:
      RESPIRA_CONFIG_B64: "<your account's sites, base64-encoded>"
      RESPIRA_CONNECTION_SOURCE: "dashboard_export"

One entry, every connected site. Hermes runs the MCP server locally over stdio, and you move between sites with the site tools instead of editing this file again.

remote, one entry per site

Prefer no key on disk? Connect straight to a site's own hosted endpoint and let Hermes run the OAuth handshake itself:

mcp_servers:
  respira:
    url: "https://<your-site>/wp-json/respira/v1/mcp"
    auth: oauth

No token sits in this file. Hermes does the full OAuth 2.1 exchange (discovery, dynamic registration, PKCE, refresh) and caches the result under ~/.hermes/mcp-tokens/respira.json.

Connecting more than one site this way means one block per site, each with its own name (respira, respira-secondsite, and so on) and its own login step.

Log in

The remote shape needs a login step after you save the file. Hermes has an in-session auto-reload for config changes, but it times out at 30 seconds, and the OAuth browser round trip usually takes longer than that. So run this from a fresh terminal rather than counting on the reload:

hermes mcp login respira

That opens your browser, you sign in to Respira and approve, and Hermes stores the refreshed token. If the WordPress tools still don't show up afterward, restart Hermes (or whatever session had the old config loaded).

Import from Claude Code

Already have Respira wired into Claude Code? Hermes can copy that setup instead of you retyping it:

hermes import-agent claude-code

This reads the mcpServers block out of ~/.claude.json and brings it into Hermes's config. Useful for a first-run migration. Once you've moved to the multi-site YAML above, that block already carries more than a single imported entry would, so there's no need to re-run the import.

Verify the connection works

A silent failure here looks exactly like success: Hermes reports the server as connected, but the WordPress tools return nothing useful. Don't take "connected" as proof by itself. Ask Hermes to do something and read the actual output:

you: list the pages on <your site>

hermes: [calls the list_pages tool]
        found 12 pages: Home, About, Services, Contact, ...

If the reply is a real list of your site's pages with titles that match what's actually in WordPress, the connection works end to end: config, auth, and the site's own API key. If Hermes says it connected but the list comes back empty, wrong, or the tool call itself errors, treat the connection as not working and go to troubleshooting below.

Troubleshooting

Nothing happens after "Add to Hermes." The deep link only fires if the desktop app is installed and running. Open Hermes first, then click the button again. If it still doesn't catch the link, use the YAML block instead.

Hermes says connected but tools return nothing. Restart Hermes. The 30-second auto-reload window can miss a config edit, so the running session may still be reading the old file, especially right after switching from the stdio shape to the remote OAuth shape.

Login opens the browser but nothing happens after you approve. Confirm you ran hermes mcp login respira in a fresh terminal, not right after editing the file in the same session that's still running. Check ~/.hermes/mcp-tokens/respira.json for a cached token; if it's missing, the login didn't complete and needs a retry.

The remote entry can't find your site. Double check the URL is exactly https://<your-site>/wp-json/respira/v1/mcp, no trailing slash, matching what WordPress reports under Settings → General.

Too many sites for one install link. Past roughly 32KB the one-click link fails silently in the desktop app. Use the YAML config instead, or install a site pack at a time from the dashboard.

Still stuck. Email word@respira.press with your Hermes version, which shape you used (stdio or remote), and what the tool call actually returned.