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

FreshBooks 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 FreshBooks 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.

Role-gating is the taught cause first: FreshBooks OAuth scopes are tied to the connected user's role, so a client-only login or a user without membership in the business the call targets gets 403 for that business's data while other calls succeed. Check which user this connection acts as before touching anything else. The second cause is the argument: an invented or copied-from-an-example client or project id returns a permission-shaped error because FreshBooks hides what the account cannot see. The advice search results give, deleting old tokens or cache and re-authenticating, assumes a token file exists; in a hosted flow there is no file, and reconnecting from the dashboard is the only re-auth that exists.

Ask the agent to diagnose it:

Call freshbooks_list_businesses and freshbooks_get_business_users. Tell me which business this connection can see and which user it acts as, then quote the exact error from the failed call. Do not retry it yet.

The search-result fix for this symptom is client-cache cleanup: delete mcp-cache.json, check stdio versus HTTP transport, or run a curl tools/list probe. Those are local-client remedies, and there is no local client here. If Hermes shows no FreshBooks tools at all, confirm the plugin installed with --enable, that both pairing commands ran, and that FreshBooks shows as connected in the dashboard, then start a fresh chat. If most tools work and a single name fails, the name is wrong rather than missing, and the error lists the closest real ones. One timing case is unique to this setup: schemas load on demand, so the opening FreshBooks call in a fresh session can arrive before the catalog and needs one retry.

Ask the agent to diagnose it:

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

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

Not one the market has found: search results repeat "FreshBooks does not provide an official first-party MCP server" across several AI Overviews, and the answers recommend third-party toolkits and GitHub wrappers instead. This page's "FreshBooks MCP for Hermes" section is the hosted equivalent of that missing server: the same FreshBooks API, exposed as tools, with the auth handled by ClawLink. If what you want is a self-hosted MCP server you run yourself, that remains a community-server task; if what you want is FreshBooks tools callable from Hermes chat, this page's setup is the route without a server.

The honest answer: read most of the account, write very little. The reads cover businesses, clients, projects, journal entries, business users, and webhooks; the writes are webhook registration and updating webhooks, plus freshbooks_register_as_a_new_user. There is deliberately no invoice creation tool in this toolkit, so an agent asked to create an invoice should say it cannot rather than invent a call. For the reading patterns agents are actually useful for, summarizing client lists, project progress, and journal activity, the toolkit is exactly sized.

FreshBooks scopes are role-gated, and this is the taught cause: a connected account with client-only login or without membership in the business the tool targets fails with 403 on that business's data, while other calls keep working. The fix is to connect a user who belongs to the business the agent should work in. Note the difference from the usual advice, which is to delete old tokens or cache and re-authenticate: there is no token file or cache in a hosted flow, so that advice does not apply here. Reconnecting from the dashboard re-issues the grant if a role changed after the connection was made.

The risk surface is small because the toolkit is small: the tool table on this page is the complete set of operations the agent can invoke, the OAuth grant is re-issuable, and revocation from the dashboard is immediate. The engine-taught advice for this provider is token and scope hygiene, which assumes you hold tokens; in this flow the tokens are held server-side and never shown to the agent. The user-side lever that matters is which account you connect, since FreshBooks scopes are role-gated and a connected user with broader access gives the agent broader reach.

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.