Agent clients

Hermes Agent

Add ShopMCP as a remote MCP server, authorize one ShopMCP workspace in your browser, and verify the live tool list before using it.

Before you start

Install or update Hermes Agent using the official installer.
Connect at least one platform in ShopMCP under Settings → Integrations.
Run Hermes on a machine where its OAuth flow can open a browser or receive a forwarded loopback callback.

The standard Hermes installer includes MCP support. If your installation does not, follow the optional MCP dependency step in the Hermes MCP guide.

1. Add ShopMCP with OAuth

Run this on the machine where Hermes Agent is installed:

bash
hermes mcp add --url https://my.shop-mcp.app/api/mcp --auth oauth shopmcp

Hermes discovers ShopMCP's OAuth metadata, registers a public client, and opens a browser. Sign in to ShopMCP, check the workspace name on the consent screen, then approve access. Do not add a token to the URL or paste an API key into Hermes.

Hermes stores the server under mcp_servers.shopmcp in ~/.hermes/config.yaml and keeps OAuth state separately under ~/.hermes/mcp-tokens/.

2. Test the live connection

Run Hermes' connection probe:

bash
hermes mcp test shopmcp

A successful test reports Connected and a discovered tool count. Unlike a config-only list command, this opens a real MCP session and proves that OAuth, protocol negotiation, and tools/list all succeeded.

3. Load ShopMCP in Hermes

Start a Hermes session with hermes chat. If the session was already open when you added ShopMCP, run:

text
/reload-mcp

Then try a bounded, read-only question:

Use ShopMCP to summarize yesterday's Shopify revenue, refunds, and top products.
Use ShopMCP to compare last week's GA4 revenue and Google Ads spend, and disclose any data gaps.

Protocol-version error

2025-11-25 is a valid MCP protocol revision. ShopMCP supports it, together with older stateful revisions. It is not the separate stateless 2026-07-28 protocol lane.

Older ShopMCP deployments stopped at 2025-06-18. Hermes versions affected by a known client bug send mcp-protocol-version: 2025-11-25 on the initial request instead of waiting for initialization to negotiate the revision. That combination produces unsupported MCP protocol version: 2025-11-25.

Temporary compatibility pin for an older ShopMCP deployment

Update ~/.hermes/config.yaml with the following header, then run /reload-mcp. Remove the pin after the server accepts 2025-11-25 so future Hermes updates can negotiate normally.

yaml
mcp_servers:
  shopmcp:
    url: "https://my.shop-mcp.app/api/mcp"
    auth: oauth
    headers:
      mcp-protocol-version: "2025-06-18"

See the Hermes protocol-header issue for the client-side root cause and workaround.

Troubleshooting

OAuth does not open or finish — run hermes mcp remove shopmcp, add it again, and complete the browser callback on the same machine. For SSH hosts, forward the loopback callback as described in Hermes' OAuth-over-SSH guide.
Connected, but no tools appear — connect at least one ShopMCP integration, run hermes mcp test shopmcp, then /reload-mcp in the active session.
Wrong workspace — remove and re-add ShopMCP, then verify the workspace name before approving OAuth.
A write is unavailable — ShopMCP writes remain controlled by workspace role, connection scope, module write toggles, and confirmation. Connecting Hermes does not enable writes by itself.