How to connect Shippo 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 Shippo from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

Shippo 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 Shippo 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 raw-API causes: a test-vs-live token mismatch, restricted carrier permissions, and a malformed Authorization: ShippoToken header. The hosted-flow equivalents: a carrier account that is not registered or activated on the connected Shippo account, an id that the connected account cannot see, or a placeholder value from documentation. There is no token to swap, so the fix is the account: check carrier registration status and the id before anything else.

Ask the agent to diagnose it:

Tell me which Shippo tool failed and quote the exact error. Then check the connected account's carrier registration status with shippo_get_carrier_registration_status and tell me what it reports. Do not retry the failed call yet.

Shippo rate-limits per endpoint and publishes its own limits table, and an agent enumerating shipments, rates, and transactions one call at a time is exactly the traffic shape that meets them. The response is not to retry harder but to narrow the work: one shipment, one order, or a date-bounded set, and the agent telling you what it intends to enumerate before it starts.

Ask the agent to diagnose it:

Tell me how many Shippo calls you made in the last minute and what you were enumerating. Quote any rate-limit detail from the last response. Do not call Shippo again until I reply.

The taught fixes for this symptom are client-config fixes: pointing the client at the right MCP endpoint, restarting, forcing tool discovery. None apply to a hosted flow. The real causes: pairing incomplete, fixed by rerunning hermes clawlink begin and hermes clawlink finish and confirming Shippo 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 Shippo tools you actually have access to. If there are none, say so plainly. If there are, tell me which one gets a shipment and use that exact name.

Try reconnecting Shippo 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 Shippo: link your Shippo account once in the browser and Hermes Agent can call the Shippo API through 95 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 Shippo 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 Shippo 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 Shippo working from chat.

No. This connects Hermes Agent, the AI assistant, to Shippo. The 'connect Shippo to Hermes' query that Google answers with carrier steps is a different intent, one answered entirely by Shippo's carrier docs, and this page does not compete with it. If you are wiring a parcel carrier into Shippo, that is Shippo's own setup flow, not this one.

No. The connection uses hosted OAuth, so there is no test-versus-live token choice and no token sitting in an environment file. The four DIY paths the engines teach, partner OAuth app, backend proxy, Platform Accounts, and Shippo's MCP server, are exactly the setups this removes: same Shippo API underneath, none of the plumbing on your side.

Live rates, addresses, parcels, shipments, orders, tracking, refunds, customs declarations and items, carrier accounts and their registration status, merchant batch, manifests, and transactions. The read surface answers 'where is this shipment, what did it cost, what are the options'; the write to be deliberate about is creating live rates, since rates and anything beyond them spend real money.

The engines' answer is that Shippo with official MCP plus OAuth is safe, with the risks being financial exposure from unconstrained label buying and prompt injection. The practical rules: reads are free, anything that purchases a label or transaction should be explicit and approved, and treat shipment content as untrusted input. Revoke the connection from the dashboard when you want it gone.

It acts as the Shippo account you authorized, with that account's carriers, addresses, and balances. A carrier that is not registered or activated on the account shows up as a permissions failure, not a missing feature, which is where the troubleshooting card below starts.

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.