Accounting MCP Accounting MCP

Connect FreeAgent

FreeAgent connects through OAuth 2.0. Accounting MCP stores the rotating access and refresh tokens in encrypted database columns and never displays them or sends them to an MCP client.

Before connecting

FreeAgent does not provide OAuth scopes. The connection inherits the access level of the FreeAgent user who approves it, while Accounting MCP's gateway tiers control which registered tools a workspace member can see and call.

Create a dedicated FreeAgent user with the minimum access needed for the five read tools. Access Level 7 is the usual starting point, but confirm the least sufficient level against the company data you expect the connector to read. Do not connect a broader administrator account by default.

Connect a company

  1. Open Connectors, choose FreeAgent, and select Connect FreeAgent.
  2. Sign in to FreeAgent and approve the application.
  3. Confirm that the company appears as Connected and Verified. Accounting MCP enables the connector only after this successful return.
  4. Grant Read access to the members or groups that need the FreeAgent tools.

Canceling the OAuth request, using the browser's Back action, or encountering an authorization error does not enable a previously disabled connector.

FreeAgent does not request a scope list. All five FreeAgent v1 tools are classified Read in Accounting MCP:

  • freeagent__list_bank_accounts
  • freeagent__list_bank_transactions
  • freeagent__list_invoices
  • freeagent__list_bills
  • freeagent__get_profit_and_loss

The gateway resolves the provider company on the server. MCP clients cannot supply a provider connection id, API URL, or arbitrary query URL.

Reconnect and verify

Select Verify to check the saved authorization against FreeAgent's current user and company endpoints. Select Reconnect when FreeAgent authorization expires, the dedicated user changes, or you need to rotate the authorization.

Access tokens are refreshed automatically before expiry. FreeAgent rotates refresh tokens; Accounting MCP updates both encrypted tokens together under a connection lock so concurrent calls do not overwrite a newer token.

Disconnect and revoke

Selecting Disconnect stops Accounting MCP from using that company immediately. This is a local disconnect: FreeAgent does not provide a programmatic revoke endpoint.

To revoke the application upstream, sign in to FreeAgent and remove Accounting MCP from the connected applications or approved apps area. Complete both steps when the authorization should no longer exist at either side.

Sandbox configuration

Developers can route new authorizations to FreeAgent's sandbox by setting freeagent.sandbox: true in Rails credentials, or the FREEAGENT_SANDBOX=true environment fallback. Client credentials belong in freeagent.client_id and freeagent.client_secret, with FREEAGENT_CLIENT_ID and FREEAGENT_CLIENT_SECRET as environment fallbacks. Never place these values in connector metadata or source control.

Sandbox and production use separate fixed API, authorization, and token endpoints. Tenant-supplied URLs are not accepted.

Next steps