FreeAgent → Claude Connector

A remote, serverless MCP connector that gives Claude access to a FreeAgent company — running entirely on a Cloudflare Worker, with nothing on your own machine. Built for the Williams of Hay rentals (properties are modelled as FreeAgent projects), but generic to any FreeAgent company.

Connect it once in claude.ai (web, desktop, phone) or Claude Code and it follows you everywhere: "which bank transactions are unexplained?", "list open invoices for 1 Lion Street", "explain that £120 payment as Repairs".

Design

Follows the Monzo → Claude connector pattern:

• @cloudflare/workers-oauth-provider front door — the Worker is a full OAuth server that Claude speaks to; grants live in an OAUTH_KV namespace.
• Upstream bridge — /authorize redirects to FreeAgent's approval page, /callback exchanges the code (Basic-auth token endpoint) and completes the grant.
• TokenStore Durable Object — the single authority for the FreeAgent token chain: all refreshes serialise through it, and a 6-hourly cron keeps the chain warm.
• Owner lock — the first FreeAgent identity to authorize owns the deployment, permanently. Anyone else is rejected before a grant exists.
• Secrets (FREEAGENT_CLIENT_ID/SECRET, COOKIE_ENCRYPTION_KEY) are Wrangler secrets — never in this repo.

Writes: journalled and undoable

Instead of a human-approval gate, safety comes from reversibility:

Guard	How
Whitelist	Only contacts, projects, invoices, bills, bank_transaction_explanations are writable
No delete tool	Deletion only happens by undoing a journalled create
Before-images	update_record snapshots the prior state into the journal first
Undo	undo_change deletes a created record / restores an updated one
Audit trail	list_changes shows every write this connector ever made
Drafts only	Invoices are created as drafts — the connector cannot send/email anything
Confirm flag	Every write tool requires confirm: true and instructs Claude to show the user first

Tools

Read: get_company, list_contacts, list_projects (= properties), list_invoices, list_bills, list_bank_accounts, list_bank_transactions, list_bank_transaction_explanations, list_categories, get_resource, connection_status.

Write: create_record, update_record, list_changes, undo_change.

Deploy

You need a (free) Cloudflare account and a FreeAgent dev app (dev.freeagent.com — note the OAuth identifier + secret).

npm install
./setup.sh     # creates the KV namespace, prompts for secrets, deploys

Then:

1. At dev.freeagent.com, add the Worker's callback as a Redirect URI: https://<your-worker>.workers.dev/callback (keep http://localhost:3000/callback too if the local Python pipeline still uses it).
2. claude.ai → Settings → Connectors → Add custom connector → https://<your-worker>.workers.dev/mcp — approve the FreeAgent login when bounced.
3. Claude Code: claude mcp add --transport http freeagent https://<your-worker>.workers.dev/mcp

Sandbox first? Set FREEAGENT_API_BASE=https://api.sandbox.freeagent.com as a Wrangler var and authorize with a sandbox account.

Ops

# token freshness + journal size (COOKIE_ENCRYPTION_KEY as bearer)
curl -s -H "Authorization: Bearer $KEY" https://<worker>/admin/status
# force a keep-alive tick
curl -s -X POST -H "Authorization: Bearer $KEY" https://<worker>/admin/cron