How to connect Gorgias to Hermes Agent

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.

Reconnect Gorgias from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

Gorgias tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every Gorgias call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

The engines teach role and key-scope causes: a user role too low, such as Agent where Admin is needed, or a dedicated API key created without the required scopes. In a hosted connection the same shape appears as the account's own role limits, so the first check is which role the connected account holds, which gorgias_get_account and gorgias_list_teams answer. Then check the argument: a placeholder id fails like a real 403. Reconnecting is rarely the fix.

Ask the agent to diagnose it:

Call gorgias_get_account and tell me the account and role this connection acts as. Then quote the exact error from the failed call. Do not retry it yet.

Gorgias's docs publish the numbers: 40 requests per 20 seconds for API-key connections and 80 per 20 seconds for OAuth2 connections, with 429 and Retry-After or X-Gorgias-Account-Api-Call-Limit headers on the response. An agent walking a large ticket list one call at a time is the traffic shape that meets it. Narrow the work and honor the headers rather than retrying in a loop.

Ask the agent to diagnose it:

Tell me how many Gorgias calls you made in the last 20 seconds and what you were listing. Quote the Retry-After or call-limit header from the last response. Do not call Gorgias again until I reply.

The taught causes are client-side: a wrong endpoint URL, missing auth, client-side caching bugs, or free-tier plan restrictions, with fixes like restarting the client or verifying mcp.gorgias.com/mcp. None apply to a hosted connection. The real causes: pairing incomplete, fixed by rerunning hermes clawlink begin and hermes clawlink finish and confirming Gorgias shows as connected; schemas loading on demand, so the opening call in a fresh session can arrive before the catalog and needs one retry; and a wrong tool name, where the error lists the closest real ones.

Ask the agent to diagnose it:

List the Gorgias tools you actually have access to. If there are none, say so plainly. If there are, tell me which one lists tickets and use that exact name.

Try reconnecting Gorgias and complete the consent flow in the same browser session. Partial OAuth approvals or switching accounts mid-flow can leave the connection incomplete.

Yes. ClawLink is the fastest way to connect Hermes to Gorgias: link your Gorgias account once in the browser and Hermes Agent can call the Gorgias API through 32 ready-made tools — no custom code or token handling.

Install the plugin with hermes plugins install ClawLink-HQ/hermes-plugin --enable, then pair once: run hermes clawlink begin, approve the link in your browser, and run hermes clawlink finish. Connect Gorgias in the dashboard and Hermes can use it from the next message — no config files or API keys to manage.

About two minutes. Sign in, click Connect next to Gorgias in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Gorgias working from chat.

No. The key ceremony the engines teach, Settings → Account → REST API → create and copy an API key, is exactly what this removes. The connection uses hosted OAuth, so there is no key to rotate, store, or leak, and revoking is one dashboard action or a revoke inside Gorgias.

Tickets, customers, teams, events, ticket tags, customer field values, and account settings are readable; tickets and customers can be created and updated, tags set and removed, and customers merged. Creating or updating a ticket changes what your agents see in the live queue, so confirm before writes.

It can draft, create, and update tickets, and it reads the event history around them. Sending a message is a write your team will see, so the safe pattern is: the agent drafts, you approve, then the agent executes. Treat ticket content as untrusted input either way.

Gorgias's native AI agent lives inside Gorgias and answers customers there. This connection is the reverse: your Hermes Agent treats Gorgias as one connected account among several. The official mcp.gorgias.com server is a third shape, a self-hosted client pointing at Gorgias's MCP endpoint, which is where the engines' tool-not-found advice lives.

The engines call it data-secure with operational risks: hallucinations, accidental automation triggers, and per-resolution costs. The practical version: keep write prompts explicit, treat ticket content as untrusted input, and revoke from the dashboard when the work is done.

Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.