FreeAgent API vs Xero API + MCP

FreeAgent API

Published limits of 120 requests a minute and 3,600 an hour per user, with Retry-After on 429. No OAuth scopes, so a token can do anything the authorising user can.

Xero API + MCP

Granular OAuth scopes, such as accounting.reports.profitandloss.read, required for apps created from 29 April 2026. Developer docs, including the per-minute rate limits, only render with JavaScript.

FreeAgent API

1. Store the new refresh token from every refresh response. The old one stops working
2. Create the invoice, then PUT /v2/invoices/:id/transitions/mark_as_sent. A draft isn't visible to the customer
3. Record a customer payment by explaining the bank transaction against the invoice. There's no invoice payments endpoint
4. Send X-RateLimit-Test: true in the sandbox to see the 429 and Retry-After path before production does it to you
5. Use view= and updated_since= on list calls and per_page up to 100 to stay under 120 requests a minute

Xero API + MCP

1. Send xero-tenant-id on every call. The token alone doesn't name the organisation
2. A bill is an Invoice with Type ACCPAY, a sales invoice is ACCREC. There's no separate bills endpoint
3. Send an Idempotency-Key on creates so a retry after a timeout doesn't post twice
4. Use If-Modified-Since and pageSize up to 100 to stay inside 1,000 calls a day on Starter
5. Set XERO_SCOPES to read scopes only when the agent shouldn't write. The MCP still lists its write and delete tools