Model Context Protocol

Connect any AI agent to your live ledger

AccountsOS exposes 94 tools via a standard MCP server. Your agent reads transactions, balances, VAT, and deadlines, or writes records with your approval. API keys are bound to a single company with explicit scopes.

Get your API key All developer docs

Endpoint: accounts-os.com/api/mcpManifest: accounts-os.com/mcp.json

What is AccountsOS MCP?

The Model Context Protocol is an open standard for connecting AI agents to external tools and data. AccountsOS implements an MCP server that exposes your live accounting data: transactions, balances, VAT returns, deadlines, documents, contacts, invoices, bills, and more.

Any agent that speaks MCP can connect. Claude Desktop, Claude Code, Cursor, or a custom agent you build yourself. The agent authenticates with an API key, calls tools against the AccountsOS endpoint, and receives structured JSON responses. Finn, the AccountsOS AI accountant, is always on and continuously available to answer questions, categorise transactions, prepare returns, and surface what needs your attention.

Endpoint

POST https://accounts-os.com/api/mcp

Bearer token authentication. JSON request and response.

Discovery manifest

https://accounts-os.com/mcp.json

Full tool list with descriptions, parameters, and the endpoint URL.

Security

Permission model

Every API key is bound to a single company. One key cannot reach another company's books. Scopes control what the key can do.

Generate an API key

In Settings, create an API key. Each key is bound to a single company and carries one or more scopes: read, write, or admin.

Read: query your books

A read-scoped key can fetch transactions, balances, deadlines, VAT summaries, documents, contacts, and reports. It cannot create or change anything.

Write: create and update records

A write-scoped key inherits all read access and can also create transactions, categorise, upload documents, and manage invoices and bills.

Admin: full control

An admin-scoped key inherits read and write access and adds destructive operations such as deleting records or managing users.

Scope reference

Scope	Grants	Example tools
read	Query transactions, balances, deadlines, VAT, documents, contacts, reports	get_transactions, get_balance, get_vat_summary, search_documents
write	Everything in read, plus create and update records	create_transaction, update_transaction, categorize_transaction, upload_document
admin	Everything in write, plus destructive and user-management operations	delete_company, manage_users

The MCP server enforces per-tool scope requirements via getToolRequiredScope. A read-scoped key calling a write tool receives a permission error. Write inherits read. Admin inherits both.

Authentication

API key (recommended)

Generate an API key from Settings → API Keys in your AccountsOS dashboard. Pass it as a Bearer token or via the X-API-Key header.

curl

curl -X POST https://accounts-os.com/api/mcp \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "tool",
    "name": "get_balance",
    "arguments": {}
  }'

Keys are bound to one company and carry explicit scopes (read, write, or admin)
Keys are stored as SHA-256 hashes; the full key is shown once at creation
Revoke any key instantly from Settings; revocation takes effect immediately

OAuth (public Finn plugin)

AccountsOS also supports OAuth-based authentication for public MCP plugins (for example, the Finn plugin in Claude Desktop). OAuth tokens are scoped to a single company. Accounts linked to more than one company are not yet supported via OAuth; multi-company selection is coming next.

Human in the loop

Finn prepares. You sign off.

MCP gives agents access to your books, but nothing consequential happens without you. Finn prepares VAT returns, reconciles transactions, drafts invoices, and runs month-end close, then presents the result for your review. Filing, submitting, and sending only happen when a human confirms.

VAT returns: Finn calculates the 9-box, you review and file
Reconciliation: Finn matches transactions, you approve the batch
Invoices: Finn drafts from documents, you check and send
Month-end close: Finn reviews the ledger, you lock the period
Annual accounts: Finn prepares FRS105, you sign and submit

FFinn

VAT return Q2 2026

Ready for review

37 transactions reconciled

4 need your attention

Invoice INV-0042 drafted

Review before sending

Nothing files, submits, or sends until you confirm.

Action log

Every AI action, recorded

Every tool call an AI assistant makes through the AccountsOS MCP server is recorded: API-key clients and Claude or ChatGPT connectors, reads and writes.

Every change Finn makes to your books is recorded too. Finn's read-only lookups are not.

Each record holds the time, the channel, the tool, whether it read or wrote, the outcome, the key or connector that made the call, and the arguments with secrets redacted.
Each change the action made to transactions, journal entries, invoices, bills, or contacts is linked to the record, with before and after values.

ai_actions row (example)

{
  "id": "5f1c9b2e-2b7a-4b1d-9f3a-8a2e6d0c4b11",
  "channel": "mcp_api_key",
  "actor_ref": "b1e7c3a0-6d2f-4a8e-9c51-3f0d2a7e8b64",
  "tool": "create_transaction",
  "is_write": true,
  "outcome": "ok",
  "duration_ms": 412,
  "created_at": "2026-09-23T09:14:02.000Z",
  "arguments": {
    "amount": 240.00,
    "description": "Office supplies",
    "category": "6500 Office Costs"
  }
}

Where to see it

Settings → Audit log → AI actions. Anyone with access to that company can see it.

Retention

Kept for as long as the company exists on AccountsOS.

Quick start

The fastest path: install the npm package and point Claude Desktop at it. For a raw HTTP integration, skip to the endpoint example above.

1. Install the MCP server

Terminal

npm install -g @thriveventurelabs/accountsos-mcp

2. Add to Claude Desktop config

claude_desktop_config.json

{
  "mcpServers": {
    "accountsos": {
      "command": "npx",
      "args": ["--yes", "@thriveventurelabs/accountsos-mcp@latest"],
      "env": {
        "ACCOUNTSOS_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

3. Restart Claude Desktop and ask

"What is my current balance?"
"Show me last month's transactions"
"When is my next VAT deadline?"
"How much did I spend on software this quarter?"

For a full walkthrough, see the Claude Desktop setup guide. For Claude Code, REST API, and CLI, see the developer hub.

Machine-readable discovery

AI agents can discover AccountsOS capabilities automatically via these standard files:

/mcp.json

MCP manifest with all 94 tools and the endpoint URL

/llms.txt

Plain-text overview, tools, auth method, and quick-start curl

/context.md

Full context document for agent comprehension

/.well-known/agent.json

A2A AgentCard (Google Agent-to-Agent protocol)

Single-company keys

Every API key is bound to one company_id at creation. There is no way to query across companies with a single key. Row-level security in the database enforces the boundary.

Per-tool scope enforcement

Each MCP tool declares a required scope (read, write, or admin). The server checks the key's scopes before executing. A read key calling a write tool gets a clear permission error.

Encrypted at rest and in transit

All traffic is TLS-encrypted. API keys are stored as SHA-256 hashes. The full key is shown once at creation and never stored. Your data is never used for model training.

Frequently asked questions

What is the Model Context Protocol?

MCP is an open standard that lets AI agents call tools on external services. AccountsOS implements an MCP server so any compatible agent (Claude Desktop, Claude Code, Cursor, or a custom build) can read and write accounting data through a single authenticated endpoint.

How is access scoped?

Every API key is bound to exactly one company. Scopes are read, write, or admin. A read-scoped key can query transactions and balances but cannot create or update records. A write-scoped key can do both. Admin adds destructive operations. One key cannot reach another company's data.

Can an agent file a VAT return or submit accounts without me?

No. Finn prepares returns, reconciliations, and accounts, but nothing is filed or submitted until a human reviews and confirms. The platform is designed so the agent does the work and the human signs it off.

Is there per-call audit logging?

Yes. Every tool call through the MCP server, API-key or OAuth, read or write, is recorded: the time, the channel, the tool, the outcome, the key or connector that made the call, and the arguments with secrets redacted. Every change Finn or an MCP client makes to your books is linked to the record it produced. See it at Settings > Audit log > AI actions.

What about OAuth for public plugins?

AccountsOS supports OAuth-based MCP authentication for public plugins (for example, the Finn plugin in Claude Desktop). An OAuth session reaches only the companies that login can already see. When that is more than one, the assistant calls list_companies and names the company on each call; the server checks every call against the user's access.

Is the API included in my plan?

Yes. MCP and API access is included on every AccountsOS plan. There is no extra charge for API calls.

Can I revoke a key instantly?

Yes. Revoke any API key from Settings. Revocation takes effect immediately; any in-flight request using that key will fail.

Connect your agent to your books

Get started free

Already a customer? Generate an API key or browse all developer docs