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

Xero Accounting 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 Xero Accounting 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 organisation is shown but greyed out, or does not appear at all, so the connection cannot be completed. Xero gives two causes: the person approving does not hold a Standard, Adviser, or Administrator role with the Connected Apps permission in that organisation, or that organisation is already connected to the app. Ask an Adviser or Administrator on the account to run the approval, or check Settings, then Connected apps, for an existing connection first.

The connection is healthy and most tools work, but one action fails at the provider with a 401 carrying an insufficient_scope header. That means the token was issued without the permission this particular action needs. Scopes in Xero are additive and cannot be edited on a token that already exists, so the fix is to reconnect: start the connection again from the ClawLink dashboard and approve the consent screen, which mints a token carrying the current scope set. Xero's own guidance is to catch the 401 and prompt to update permissions rather than retrying the same call.

A filtered read comes back empty and the agent concludes you have no matching invoices or transactions. Before believing it, suspect the filter. Xero's OData-style where clause returns an empty result rather than an error when the expression is malformed or a field name is wrong, so a typo reads exactly like an empty account. Field names are case-sensitive and exact (Status, Type, IsReconciled, BankAccount.AccountID), and string values need double quotes. Ask the agent to re-run the read with no where clause at all; if rows come back, the filter was the problem, not the books.

This is the provider's own message, and it means the sign-in worked but no organisation is attached to the connection any more. Three causes are common: consent was completed without an organisation being authorised, someone disconnected the app inside Xero (Settings, then Connected apps), or the connection sat unused for 60 days or more, which is when Xero expires an unused refresh token. The fix is the same in every case: reconnect from the ClawLink dashboard and approve the organisation on Xero's consent screen.

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

No. You approve Xero in the browser through its normal consent screen, and ClawLink holds the credential; there is no trip to the Xero developer portal, no app to register, and no client secret to paste into a config file. This is the main practical difference from the self-hosted route. Xero's own open-source MCP server asks for a Custom Connection, which is a premium integration option: the Xero organisation has to buy a Custom Connection subscription before it can be authorised at all, it is only offered to organisations in Australia, New Zealand, the UK, and the US, and one connection reaches exactly one organisation. Those are Xero's terms for that connection type, not a criticism of the server.

No, and the distinction is worth being precise about because the two things get conflated. Xero's Developer Platform Terms, last updated 4 December 2025, say that you "must not use API Data sourced from the Xero developer platform to train or fine tune any artificial intelligence models". That is a restriction on training models with the data, and ClawLink does not do it. It is not a ban on connecting an agent: reading your own invoices on demand, in response to something you asked, is ordinary API use and is what the tools below do. Anything the agent reads goes into that one answer, not into a training set.

The honest answer has three parts. First, the credential: you approve access on Xero's consent screen and the token stays on the ClawLink server rather than in a file on your machine, so revoking it is a click in Xero (Settings, then Connected apps) or in the ClawLink dashboard, and it stops working immediately. Second, the blast radius: the agent acts with the permissions of whoever approved the connection, on the single organisation approved, and it can write. Invoice, payment, contact, and manual journal tools post to your real books, so treat write prompts the way you would treat handing someone your Xero login. The financial reports are read-only and cannot change anything, which makes reporting the sensible place to start. Third, what we do not request: the connection asks for Xero's granular scopes rather than the deprecated broad ones, and it does not request accounting.journals.read, so the general ledger feed is out of reach by construction.

Manual journals, yes: xero_create_manual_journal and xero_update_manual_journal are in the tool list along with the matching read tools, so books-level adjustments work end to end. The read-only general ledger feed is a different thing: Xero restricts its Journals endpoint to apps on its Advanced developer tier, so it is deliberately not in the list. For ledger-level review, use the report tools and xero_list_manual_journals instead.

Profit and loss (xero_get_profit_loss_report), balance sheet (xero_get_balance_sheet_report), and trial balance (xero_get_trial_balance_report), plus budgets through xero_get_budget. All of these are read-only, so a reporting workflow cannot change anything in your books, which makes reports the safe first prompt to try after connecting.

Yes. Each ClawLink connection is tied to the organisation you approve on Xero's consent screen. To work across several organisations, add another connection from the dashboard and tell the agent which one a task should use; when you do not say, the default connection is used. xero_get_organisation shows which organisation a connection is acting as, which is the quickest check when numbers look unfamiliar.

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.