# How to connect FreeAgent to Hermes Agent (no API keys)

> Connect FreeAgent to Hermes Agent with ClawLink: 76 tools from chat via hosted OAuth. No developer app to register, no client secret to hold.

Web version: https://claw-link.dev/hermes/freeagent

Most guides for giving Hermes Agent FreeAgent access start with registering your own OAuth app or pasting API keys into env files, then leave the token refresh and tool wiring to you. ClawLink gives Hermes a more practical FreeAgent setup: pair once in the browser and your always-on Hermes agent can act on FreeAgent for you, reading and doing real work on your behalf with no auth, token refresh, or tool wiring to build yourself.

**Start here — paste this into Hermes to set up ClawLink:**

> Set up ClawLink for Hermes and tell me when it's ready.
> 1. Install the plugin: `hermes plugins install ClawLink-HQ/hermes-plugin --enable`
> 2. Start pairing with `hermes clawlink begin`. It prints an approval link, so show me the link and stop, don't wait.
> 3. I'll approve it in my browser, then reply "approved".
> 4. When I say approved, finish setup: `hermes clawlink finish`
> 5. Then run `hermes clawlink test` and tell me whether ClawLink is ready.

## Setup

It takes three steps to connect Hermes to FreeAgent.

1. **Install ClawLink** — add the plugin to Hermes Agent once.
2. **Connect FreeAgent** — one-click OAuth in the ClawLink dashboard.
3. **Use it from chat** — ask Hermes Agent in plain English.

**Alternative for any agent (no plugin needed):** if the Hermes Agent plugin route isn't available or doesn't work, any AI agent with shell access can use the ClawLink CLI instead:

```bash
npx -y @useclawlink/cli login          # sign in via browser — no API key to paste
npx -y @useclawlink/cli connect freeagent  # connect FreeAgent (browser OAuth)
npx -y @useclawlink/cli actions freeagent  # list available actions
npx -y @useclawlink/cli run freeagent <action> --input '<json>'  # execute (add --confirm for writes)
```

The whole pairing handshake. Run these once, then approve FreeAgent in the dashboard:

```bash
hermes plugins install ClawLink-HQ/hermes-plugin --enable
hermes clawlink begin     # approve the link in your browser
hermes clawlink finish
hermes clawlink test
```

Notice what is missing: no developer account, no app registration, no client secret. The OAuth 2.0 flow the search results say you must do yourself happens here on the hosted side; you only approve it in the browser.

### Using a different agent?

The Hermes plugin is one client of ClawLink's MCP server. Claude Code, Cursor, Codex, or any agent that can run a shell command pairs with the same ClawLink account through the CLI:

```bash
npx -y @useclawlink/cli login
```

`login` opens the same browser approval and stores a credential locally. Once FreeAgent is connected in the dashboard, that agent calls the same 76 FreeAgent tools over MCP. Full setup for MCP clients and shell agents: [connect apps to any AI agent](https://claw-link.dev/learn/connect-apps-to-any-ai-agent).

## FreeAgent MCP for Hermes

Looking for a FreeAgent MCP server for Hermes Agent? ClawLink connects FreeAgent to Hermes Agent and exposes 76 FreeAgent tools your agent can call over [MCP](https://claw-link.dev/learn/what-is-an-mcp-server), with [hosted auth](https://claw-link.dev/learn/oauth-for-ai-agents) and nothing to run or maintain yourself. Using OpenClaw instead? The [OpenClaw FreeAgent integration](https://claw-link.dev/openclaw/freeagent) works the same way.

FreeAgent has no personal access tokens. If you follow the search results, the next step is creating a developer account, registering an app, and completing the OAuth 2.0 flow yourself, then holding the client secret. That is the exact setup this page removes: the app registration and the credential storage happen once on the hosted side, and you only approve the connection in the browser. Your Hermes Agent then calls 76 FreeAgent tools against your company's books: invoices, estimates, contacts, bills, bank accounts, timeslips, cashflow summaries, and the P&L.

## What the Hermes Agent FreeAgent integration can do

76 FreeAgent tools are ready for Hermes Agent once the account is connected. The 30 below are the ones people reach for most; your agent can call all 76.

### 30 of 76 FreeAgent tools for Hermes

| Tool | What it does |
|---|---|
| **Cashflow summary for a given date range** `freeagent_cashflow_summary_for_a_given_date_range` | Get cashflow summary for a date range from FreeAgent |
| **Company details** `freeagent_company_details` | Get company details from FreeAgent |
| **Create a timeslip** `freeagent_create_a_timeslip` | Create a new timeslip in FreeAgent |
| **Create bank account** `freeagent_create_bank_account` | Create a bank account in FreeAgent |
| **Create bill with attachment** `freeagent_create_bill_with_attachment` | Create a bill with optional attachment in FreeAgent |
| **Create contact** `freeagent_create_contact` | Create a new contact in FreeAgent |
| **Create estimate** `freeagent_create_estimate` | Create a new estimate in FreeAgent |
| **Create invoice** `freeagent_create_invoice` | Create an invoice in FreeAgent |
| **Get the pl summary** `freeagent_get_the_pl_summary` | Get the profit and loss summary from FreeAgent |
| **List accounting transactions** `freeagent_list_accounting_transactions` | List accounting transactions in FreeAgent |
| **Get invoice timeline** `freeagent_get_invoice_timeline` | Retrieve invoice timeline showing chronological record of invoice-related events |
| **Get mileage settings** `freeagent_get_mileage_settings` | Retrieve mileage settings including engine type/size options and reimbursement rates |
| **Get opening balances** `freeagent_get_opening_balances` | Retrieve the Opening Balances journal set for a company |
| **Get personal profile** `freeagent_get_personal_profile` | Retrieve the authenticated user's personal profile from FreeAgent |
| **Get the opening balances** `freeagent_get_the_opening_balances` | Retrieve the opening balances from the trial balance summary |
| **Get the trial balance summary** `freeagent_get_the_trial_balance_summary` | Get the trial balance summary from FreeAgent |
| **List accounting balance sheet** `freeagent_list_accounting_balance_sheet` | Retrieve the balance sheet for a FreeAgent account |
| **List accounting balance sheet2** `freeagent_list_accounting_balance_sheet2` | Retrieve opening balances for the balance sheet from FreeAgent |
| **List all cis bands for a company** `freeagent_list_all_cis_bands_for_a_company` | List all CIS (Construction Industry Scheme) bands for a company |
| **List all expenses** `freeagent_list_all_expenses` | List all expenses from FreeAgent |
| **List all price list items** `freeagent_list_all_price_list_items` | List all price list items from FreeAgent |
| **List all properties** `freeagent_list_all_properties` | List all properties in FreeAgent |
| **List all recurring invoices** `freeagent_list_all_recurring_invoices` | Retrieve a list of recurring invoices from FreeAgent |
| **List all sales tax periods for a company** `freeagent_list_all_sales_tax_periods_for_a_company` | List all sales tax periods for a company in FreeAgent |
| **List all stock items** `freeagent_list_all_stock_items` | List all stock items from FreeAgent |
| **List all tasks** `freeagent_list_all_tasks` | List all tasks in FreeAgent |
| **List all timeslips** `freeagent_list_all_timeslips` | List all timeslips from FreeAgent |
| **List all users** `freeagent_list_all_users` | List users in FreeAgent |
| **List bank accounts** `freeagent_list_bank_accounts` | List bank accounts in FreeAgent |
| **List bank feeds** `freeagent_list_bank_feeds` | List all bank feeds for a company |

## Example prompts

**Cashflow view**

> Use freeagent_cashflow_summary_for_a_given_date_range for last quarter, then list accounting transactions with freeagent_list_accounting_transactions and tell me the three line items that moved the most.

**Draft an estimate**

> Create an estimate with freeagent_create_estimate for \<contact> using the price list items you can see, and show it to me before it is sent.

**P&L in plain words**

> Pull freeagent_get_the_pl_summary and explain the change against the previous period in plain language, calling out the largest movements.

**Timesheet check**

> List all timeslips with freeagent_list_all_timeslips for this month and flag any that are missing a task or project.

## How the FreeAgent tools behave

Details that matter once the connection is live and the agent is reading your books.

- **Company-scoped.** One FreeAgent account is one company; every tool acts on that company.
- **Financial summaries are first-class tools.** Cashflow, P&L, trial balance, balance sheet, and opening balances are direct calls, not screen-scraping.
- **Invoices and estimates are creations with side effects.** Creating one changes the accounting picture; bills accept attachments.
- **Users and permissions are readable.** `freeagent_list_all_users` and `freeagent_get_personal_profile` answer 'what can this connection do' before a 403 forces the question.
- **The long tail is real.** Recurring invoices, stock items, price list items, CIS bands, sales tax periods, and properties each have their own list tools.
- **Writes need confirmation.** Creating invoices, estimates, bills, and bank accounts moves real numbers; state the confirmation step in the prompt.

## ClawLink vs. building it yourself

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 FreeAgent working from chat.

| | Manual | ClawLink |
|---|---|---|
| **Connection flow** | Register a FreeAgent app, configure redirect URLs, manage consent details, and reconnect users when auth settings drift. | Users connect FreeAgent through the hosted browser flow and ClawLink keeps the token lifecycle out of your app code. |
| **Ongoing maintenance** | You own refresh logic, permission debugging, environment config, and every provider-specific edge case for FreeAgent. | ClawLink handles the repetitive integration plumbing so your team can focus on the workflow instead of the infrastructure. |
| **Agent usability** | You still need to expose the right FreeAgent actions to the runtime in a format your agent can reliably use. | 76 tools for FreeAgent are already exposed through ClawLink, so the agent can read and act from chat immediately. |

## ClawLink vs. Composio

Composio also exposes FreeAgent to AI agents. It is developer infrastructure: Python and TypeScript SDKs, an MCP server, and a catalog past 1,000 apps, aimed at teams shipping agent products. ClawLink is built for Hermes Agent users instead. You install the plugin once, connect FreeAgent in the browser, and the 76 tools above work from chat. There is no SDK, no config file, and no API key handling. Choosing between them? Read the full [Composio alternatives](https://claw-link.dev/hub/composio-alternatives) comparison.

### Hermes paired but still can't use FreeAgent
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`.

### Connection succeeds but no tools appear
Reconnect FreeAgent from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

### "Tool schema not loaded yet" error when calling FreeAgent tools
FreeAgent 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 FreeAgent 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.

### FreeAgent returns 403 or "permission denied" on one action while others work
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.

### FreeAgent returns 403 or "insufficient permissions"
The engines name causes from the raw-API world: a user permission level too low for the endpoint, locked or filed accounting periods that reject writes from any client, and a sandbox-versus-production mismatch between the credential and the environment. The hosted-flow equivalents: the connection was authorized under a user whose permission level cannot reach the endpoint, in which case `freeagent_get_personal_profile` and `freeagent_list_all_users` show who can; or the agent passed a placeholder value from documentation, which fails like a permissions error on a strict API. Reconnecting is rarely the fix; check the user and the argument first.

Ask the agent to diagnose it:

```text
Call freeagent_get_personal_profile and tell me the user and permission level this connection acts as. Then quote the exact error from the failed call. Do not retry it yet.
```

### FreeAgent calls stall or hit rate limits on a big list
FreeAgent rate-limits its API, and the traffic shape that meets the limit is an agent enumerating accounting transactions or timeslips one call at a time. The response is not to retry immediately but to change the shape of the work: narrower date ranges, fewer records per call, and the agent telling you what it intends to enumerate before it starts. If a bulk review is genuinely needed, running it in stages across a few turns is more reliable than one sweep.

Ask the agent to diagnose it:

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

### 'Tool not found' or FreeAgent tools missing
The taught fixes for this symptom are all self-hosted: edit `claude_desktop_config.json` or `mcp.json`, fix absolute paths, rebuild `/dist/index.js`, force tool discovery. None of that applies here, because there is no local server. The hosted causes are: pairing incomplete, fixed by rerunning `hermes clawlink begin` and `hermes clawlink finish` and confirming FreeAgent 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:

```text
List the FreeAgent tools you actually have access to. If there are none, say so plainly. If there are, tell me which one fetches the P&L summary and use that exact name.
```

### OAuth finished in the browser but the account is still missing
Try reconnecting FreeAgent and complete the consent flow in the same browser session. Partial OAuth approvals or switching accounts mid-flow can leave the connection incomplete.

### Is there a Hermes Agent FreeAgent integration?
Yes. ClawLink is the fastest way to connect Hermes to FreeAgent: link your FreeAgent account once in the browser and Hermes Agent can call the FreeAgent API through 76 ready-made tools — no custom code or token handling.

### How do I connect FreeAgent to Hermes with ClawLink?
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 FreeAgent in the dashboard and Hermes can use it from the next message — no config files or API keys to manage.

### How long does it take to connect FreeAgent to Hermes Agent?
About two minutes. Sign in, click Connect next to FreeAgent in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

### Why use ClawLink instead of wiring FreeAgent up myself?
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 FreeAgent working from chat.

### Do I need to register a FreeAgent developer app?
No. Search results teach app registration as the only path because FreeAgent genuinely has no personal access tokens. The hosted route registers and runs the OAuth app for you: you approve the connection in the browser, pairing is two Hermes commands, and no client secret file ever lands on your machine. The OAuth 2.0 flow is the same flow; the difference is who runs it.

### What can the agent do in FreeAgent?
Company details, invoices, estimates, bills with attachments, contacts, bank accounts, timeslips, mileage settings, cashflow summaries for a date range, profit and loss, trial balance, balance sheets, opening balances, accounting transactions, stock items, recurring invoices, price list items, users, and bank feeds. Creating invoices, estimates, bills, contacts, bank accounts, and timeslips are the writes to be deliberate about, since they change the accounting picture.

### Which company does the agent act as?
FreeAgent accounts are company-scoped: one account is one company, and every tool acts on that company. There is no cross-company surface to configure, which also means there is no wrong-company failure mode to debug.

### Can it create and send invoices?
It can create invoices and estimates, and bills with attachments. Whether it sends them depends on what you approve: the create tools produce the document, and sending is a separate action you should confirm explicitly. A created invoice is a real document in your books either way.

### Is it safe to connect FreeAgent to an agent?
The engines answer 'safe if you use official OAuth 2.0, limit permissions, and use a secure gateway', with prompt injection and over-privileging as the taught risks. This connection is official OAuth 2.0 run hosted, with the token held server-side and revocable from one dashboard. The practical discipline is the same as anywhere: keep write prompts explicit and treat anything the agent reads from invoices or bills as untrusted input.

### Hermes paired but still can't use FreeAgent
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`.

## Related

- [Zoho Books tools](https://claw-link.dev/hermes/zoho-books) — Organize finances, invoices, bills, and accounting
- [Zoho Invoice tools](https://claw-link.dev/hermes/zoho-invoice) — Create and send invoices, track payments, and manage billing
- [Square](https://claw-link.dev/hermes/square) — Process payments and manage POS