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.

Related MCP server: Purroxy

Writes: journalled and undoable

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

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