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

Square 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 Square 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 standard advice assumes a personal access token you regenerate in the developer dashboard, and that is the wrong fix here, because the connection is an OAuth grant with no token you own. An expired or revoked grant produces a 401 while the dashboard still shows the connection as connected, and a grant whose scopes changed after a Square-side policy update behaves the same way. The toolset has the right diagnostic for this: square_retrieve_token_status reports token validity, expiration, and authorized scopes. If it confirms the grant is stale, the recovery is to reconnect Square from the ClawLink dashboard, which re-runs the consent flow and replaces the stored grant. A refund on a payment that Square has already cancelled produces a similar-looking error; check the payment state before assuming the connection broke.

Most Square endpoints require a location_id, and a wrong or missing location is the most common way a 403 appears while other tools keep working: the connection is fine, the location is not. Get real ids from square_list_locations instead of letting the agent invent them. The second cause is scope: the OAuth grant carries the permissions approved at consent, and a tool that needs CUSTOMERS_WRITE or a payments scope the grant lacks will 403 on that call alone. Reconnect from the dashboard to re-run consent if you need a wider grant. The third is merchant state: a suspended or unverified seller account produces permission-shaped errors across the board, which is a Square-side check, not a connection fix.

Square does not publish fixed rate limits; limits are dynamic, applied per endpoint and per location, and can change without notice. What that means in practice is a bursty agent (a list_payments loop across months, or create_order calls in a tight loop) can trip a 429 response that has no documented number behind it. The response carries the instruction to slow down, and the fix is exponential backoff, not reconnecting: reconnect changes nothing, because the limit is on Square's side. Shape the work instead: one square_search_orders call with a date range beats thirty list calls, and batch catalog reads into square_search_catalog_objects.

Search results blame a local MCP registry: malformed configuration in Cursor, a null-field bug in Claude Desktop, formatting errors in a config file. There is no local MCP registry in this setup, so those fixes do not apply. Here, Square tool schemas load on demand the first time a tool runs, and a call in a fresh chat can arrive before the catalog is hydrated; retrying once resolves it. If the same name fails twice, the name is wrong rather than missing, and the error message lists the closest real tools. Reconnect from the dashboard if every Square call keeps failing in a fresh chat.

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

No. The official Square MCP server requires a Square developer app, sandbox credentials, and access token management, which is what the "best square mcp server" answers teach. This connection goes through Square's OAuth flow against your seller account: you approve it in the browser, and no developer dashboard is involved. The agent inherits what your Square account can reach, the same way a user-approved integration would.

Your live seller account. Sandbox credentials belong to a developer application and a specific sandbox location, and this flow creates neither, so there is no sandbox environment to point at. Everything the agent reads or writes, from square_list_payments to square_create_order, is against the account you approved.

The read side is reconciliation and operations: square_list_payments by location and time range, square_search_orders across locations, customer profiles, catalog objects, inventory counts, and locations (square_list_locations returns the location ids the other tools need). The write side is real money movement: square_create_order builds orders, square_create_refund returns funds for a completed payment, and square_accept_dispute and evidence tools sit on top of disputes. Ask for reads and drafts first; approve refunds and order submissions before they go.

The engines answer this with enterprise security vendor copy about least privilege and human approval, and none of them mention the model this product uses: connect in the browser, revoke in the dashboard. The grant is visible in your Square account, revocation is immediate, and there is no token file on the machine running your agent. The part the vendors are right about is human approval on writes, and the money-moving tools above are exactly where that applies. An agent that drafts a refund and waits for your confirmation behaves like a cautious teammate; an agent that executes refunds unprompted is a liability no connection model fixes.

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.