All posts
Project

Chat to your books: a FreeAgent MCP server

We built a secure bridge from FreeAgent to ChatGPT, so our real books can answer questions and get work done in the chat we already use.

5 minDmitriy Ginzburg

Accounting software is a set of screens. You open the app, find the right report, read the number, and go back to what you were doing. That is fine once a month. Once an hour it gets tiring.

A remote MCP⁠ server changes that. It puts your accounting system behind one link that AI assistants already know how to use. You ask a question in plain English and the answer comes straight from your real books. No exports, no spreadsheets, no copy and paste. The same connection can also make changes, so you can ask it to do things too: raise the invoice, send the reminder, post the journal.

We built one for FreeAgent⁠. It runs on Cloudflare, it is locked behind a proper sign in, and any app that supports MCP can connect to it.

What it feels like to use

You are on the train with ChatGPT open on your phone. You type "Which invoices are overdue, and by how much?" and you get the list from your actual books, not a guess. Then "Email a reminder for the two oldest." FreeAgent sends them with its own email template. On a ChatGPT Business or Enterprise plan this works on your phone and on the web, so your books are as easy to reach as your messages.

At your desk it is the same server, just opened from a different app. Claude or Cursor can match a bank payment to an expense, work out what hosting really cost last year, or draft this month's depreciation journal. If the journal does not balance, the server will not post it. Ask "Are we profitable this quarter, and where did the money go?" and you get a straight answer with the categories behind it, in less time than it takes to open FreeAgent.

You can plug it into your own software as well. Our internal dashboard connects to it like any other app. That is how a small company ends up with a bookkeeping assistant inside its own admin area without building an accounting integration from scratch. Scheduled jobs can use it with nobody watching, for example one that checks every morning for bank transactions nobody has explained yet and only messages you when it finds some.

Who it is for

If you own a small business or run one as a director, this is the difference between "I'll look at the numbers on Sunday" and knowing where you stand the moment you wonder. If you are an accountant or bookkeeper, it takes care of the repetitive half of the job (chasing, categorising, reconciling, month end journals) because you ask for it instead of clicking through it. FreeAgent stays the one place where the numbers live. Nothing is copied into another tool and nothing is made up: every answer comes from a live request to FreeAgent.

It is worth being honest about the limits. An assistant that can make changes is still an assistant. Treat it like a capable junior: check what it posts, and only give write access to people you would trust with it anyway. The real change is not that AI does your accounting. It is that getting a reliable answer about your own business now takes one sentence.

What it can do

The server offers 56 tools on top of FreeAgent's API:

  • Reports: profit and loss, balance sheet, trial balance, opening balances.
  • Documents: invoices (including sending them and marking them paid), bills, expenses, credit notes.
  • Banking: accounts, transactions and their explanations.
  • Bookkeeping: journals, categories and nominal codes. Any journal that does not balance is rejected.
  • Everything else: contacts, projects, estimates and timesheets to read, plus a safe general request tool for the parts of the API we have not covered yet.

Before it starts, the AI gets a short guide to how FreeAgent works: every record is identified by its link, categories are nominal codes, dates use the standard year, month, day format, and a journal must add up to zero. That one page is the difference between an assistant that stumbles and one that sounds like it has used FreeAgent for years.

How it is built

Cloudflare Workers + Durable Objects

Cloudflare Workers + Durable Objects

The whole server is one Worker. A Durable Object keeps the single FreeAgent connection for the company and refreshes it one request at a time, so no app ever sees a FreeAgent token. A second one stores who may write and delete, so that can change without a redeploy.

Cloudflare Access

Cloudflare Access

Sits in front of the server and checks who you are. People sign in with a code sent to their email; scripts use a service token. The Worker only trusts the signed identity that Access attaches to each request.

Model Context Protocol

Model Context Protocol

Built with Cloudflare's Agents SDK and the official TypeScript SDK. Any app that supports MCP connects with nothing more than the link.

FreeAgent API

FreeAgent API

A clean API whose sign in lasts a long time, which is what makes one shared connection for the whole company practical. A sandbox account is used for development and the real account for the live server.

Convex + Next.js

Convex + Next.js

Our admin dashboard connects to the server like any other app. It signs each administrator in, stores their access securely, and shows on an Integrations card whether the connection works and what that person is allowed to do. The server sees the real person, not a shared key.

How it stays safe

The obvious worry is giving an AI the keys to your books, so here is how that is handled. Everyone who can sign in can read. Named people can make changes. Deleting is off unless an owner switches it on. If someone is not allowed to use a tool, their app never even sees it, so there is nothing to talk the AI into.

  • Nothing reaches the server without a valid sign in through Cloudflare Access. No API keys pasted into chat apps, no VPN, no lists of allowed IP addresses.
  • FreeAgent's tokens never leave the server. Your app signs in to Cloudflare, and the server signs in to FreeAgent. The two never meet.
  • Permissions belong to the person, not the app. You get the same access from ChatGPT, Claude, Cursor or a script, and if a laptop goes missing you remove that person in one place.
  • Changing who can write is a setting, not a code change. An owner updates it on a small page served by the server itself.
  • Every tool call is logged with who made it, which tool, whether it worked and how long it took. The content of requests and answers is not logged.

None of this is unusual, and none of it is special to FreeAgent. Any business running on software with a decent API can be reached the same way. For now, that is about the most modern way there is to work with your own numbers.