The Tolvi MCP server for AI assistants

The Tolvi MCP server gives an AI assistant, such as Anthropic's Claude, a set of tools over the Tolvi API: your work queue, deadlines, engagements, trial balances and review points, and read-only access to your clients' Tolvi Books. It acts as you, with your permissions, and it can never sign off or approve.

Last updated 1 November 2026

Can I use it today?

ComingNot yet. Connecting an assistant to Tolvi is coming next. The MCP server and its tools are built and tested, but the sign-in an assistant needs to connect isn't set up yet. We don't give dates. This page describes what it will do, so you can plan for it.

What is the Tolvi MCP server?

The Model Context Protocol (MCP) is an open standard for giving AI assistants tools. The Tolvi MCP server is a remote MCP server at https://mcp.tolvi.co.uk/mcp. It's a thin layer over the public Tolvi API: each tool calls the API with your own token, so permissions, firm separation and the audit log work exactly as they do in the app. No business rules live in the MCP server.

An assistant using the MCP server runs on your own AI plan, such as a Claude plan, so it doesn't use Tolvi AI tokens.

Which transport and sign-in does it use?

Streamable HTTP. The assistant sends JSON-RPC requests as POSTs to https://mcp.tolvi.co.uk/mcp, and answers come back as JSON or an event stream. A session starts with initialize, is identified by the Mcp-Session-Id header, belongs to the person who opened it and ends after 30 minutes idle.
OAuth 2.1. Every request carries a bearer token. The server publishes its protected-resource metadata (RFC 9728) at https://mcp.tolvi.co.uk/.well-known/oauth-protected-resource/mcp, which names Tolvi's identity provider and the scopes. The assistant signs you in through your browser with PKCE, and you approve the scopes it asks for.
Tokens for this server only. A token is accepted only if it was issued for https://mcp.tolvi.co.uk/mcp (RFC 8707 resource indicators), so a token for another service can't be replayed here.
The same scopes as the API. What a tool can do is your role intersected with the scopes you granted, exactly as for API tokens.

Which tools does it have?

The Tolvi MCP server has 42 tools: 39 read-only tools and 3 that make a change after you confirm it. 23 of the read-only tools are for Tolvi Books. Each one needs the scopes listed, and your role must allow it too.

Working papers, the work queue and Meetings

Working papers, the work queue and Meetings: tools on the Tolvi MCP server
Tool	What it does	Kind	Scopes
`list_my_work` List my work	Your work queue: engagements, deadlines, stage and who acts next, in any saved view (mine, review, returned, due in 30 days, overdue, changed since sign-off, open, all, at risk, unassigned).	Read-only	`work:read`
`find_clients` Find clients	Searches the firm's clients by name or Companies House number.	Read-only	`clients:read`
`get_client_record` Get client record	One client’s central record in Tolvi Hub: status, services, tax references, responsible partner, client manager, contacts and notes, with where its year ends, meetings and books stand.	Read-only	`clients:read`
`get_client_overview` Get client overview	One client across the suite: status, next deadlines, latest figures and tax due from each product this connection can use.	Read-only	`clients:read`
`list_self_assessment_returns` List self assessment returns	Clients’ SA100 returns with their status and days to the deadline. Approving and filing stay with people in the app.	Read-only	`self_assessment:read`
`get_self_assessment_return` Get self assessment return	One return’s tax calculation, what HMRC’s rules would refuse and open review points, never National Insurance numbers or dates of birth.	Read-only	`self_assessment:read`
`get_self_assessment_plan` Get self assessment plan	Which pages a return needs from the answers so far, the questions still open, and any page Tolvi can’t prepare yet.	Read-only	`self_assessment:read`
`search` Search Tolvi	One search across clients, engagements, meetings and people, plus the sections of an engagement, limited to what the connection may read.	Read-only	`clients:read`
`get_bookkeeping_connection` Get bookkeeping connection	Whether a client's Xero, QuickBooks, Sage or FreeAgent is connected, which organisation, and when the books were last read. Status only.	Read-only	`clients:read`
`deadlines_this_month` Deadlines this month	Open engagements with a filing deadline in a calendar month (this month by default, UK time), soonest first: yours, or every one you can see.	Read-only	`work:read`
`assign_engagements` Assign engagements	Changes the preparer, reviewer or manager on one or more engagements. Needs the Manager role.	Asks you first	`engagements:write` `work:read`
`get_engagement_status` Get engagement status	One engagement: client, period, deadline, workflow stage, amendment rounds, open review points, the trial balance version and each section’s sign-off status.	Read-only	`engagements:read`
`get_next_steps` Get next steps	Your next step on an engagement and on each section, with the outstanding items in order.	Read-only	`engagements:read`
`get_trial_balance` Get trial balance	The final trial balance (draft TB plus posted journals), for the whole engagement or one section, with last year’s figures.	Read-only	`engagements:read`
`list_review_points` List review points	Review points on an engagement with their latest message, filtered by status or section.	Read-only	`engagements:read` `work:read`
`raise_review_point` Raise a review point	Raises a review point on a section or the whole engagement. Needs the Reviewer role. On reviewed work it withdraws the review sign-off, as it does in the app.	Asks you first	`review:write` `engagements:read`
`comment_on_review_point` Comment on a review point	Adds a comment to a review point's thread. It doesn't answer, clear or reopen the point.	Asks you first	`engagements:write` `engagements:read`
`list_meetings` List meetings	Tolvi Meetings: the meetings a note-taker was sent to, newest first, optionally only one client’s, with their status and number of next steps.	Read-only	`meetings:read`
`get_meeting` Get meeting	One meeting’s write-up: summary, takeaways, next steps (owner and deadline), open questions and the draft follow-up email, and the transcript if asked for. The recording itself is not kept.	Read-only	`meetings:read`

Tolvi Books (read-only)

Tolvi Books (read-only): tools on the Tolvi MCP server
Tool	What it does	Kind	Scopes
`list_linked_businesses` List linked businesses	The businesses whose Tolvi Books your practice can reach through a link, the client each is linked to, the access it gave, and the books at a glance. Gives the business id the other Books tools need.	Read-only	`client_books:read`
`get_getting_started` Get the getting started list	The steps to set up the books and which are done.	Read-only	`books:read`
`get_books_summary` Get Books summary	The business’s Home: money in and out, profit so far this year, cash, who owes it and whom it owes, VAT owed, the tax to set aside (an estimate) and what needs the owner.	Read-only	`books:read`
`get_inbox` Get the Books inbox	What needs the owner now: questions about bank lines, suggested groups, matches, rule offers, receipts to check and reminders to approve. Confirming and undoing stay in Tolvi Books.	Read-only	`books:read`
`list_books_accounts` List Books accounts	The chart of accounts with each account’s balance and the plain-English name the owner sees.	Read-only	`books:read`
`get_books_trial_balance` Get Books trial balance	The trial balance of the books at a date, worked out from posted entries.	Read-only	`books:read`
`get_profit_and_loss` Get profit and loss	Profit and loss for any period, with a comparison.	Read-only	`books:read`
`get_balance_sheet` Get balance sheet	What the business owns and owes at a date, with a comparison.	Read-only	`books:read`
`get_aged_report` Get aged debtors or creditors	Who owes the business, or whom it owes, by how overdue, with each unpaid item.	Read-only	`books:read`
`get_cash_flow` Get cash flow by month	Money in and out of the bank, cash and card accounts, month by month.	Read-only	`books:read`
`get_sa103_totals` Get SA103 totals	For a sole trader, the income and expense boxes of SA103F for a tax year, from the chart.	Read-only	`books:read`
`list_bank_lines` List bank lines	Bank lines still to explain (or explained, or excluded), with Tolvi’s suggestion for each and why.	Read-only	`books:read`
`list_receipts` List receipts	Receipts and bills awaiting review, with what Tolvi AI read from each, its best bank match and any duplicate warning.	Read-only	`books:read`
`list_invoices` List invoices	Sales invoices and credit notes, with what is still owed and how overdue.	Read-only	`books:read`
`get_invoice` Get invoice	One invoice or credit note: lines, VAT, totals, payments, emails sent and reminders.	Read-only	`books:read`
`list_bills` List bills	Bills and supplier credits, with what is still to pay and how overdue.	Read-only	`books:read`
`get_bill` Get a bill	One bill with its lines, payments and credits.	Read-only	`books:read`
`get_purchases_summary` What the business owes suppliers	What the business owes and how much is overdue, by supplier.	Read-only	`books:read`
`list_suppliers` List suppliers	Suppliers, with what is owed to each.	Read-only	`books:read`
`get_sales_summary` Who owes what	What customers owe the business and how much is overdue, by customer.	Read-only	`books:read`
`list_recurring_invoices` List repeating invoices	Repeating invoices running or paused: who for, how much, how often and the next date.	Read-only	`books:read`
`get_vat_summary` Get VAT summary	The VAT scheme, the next return and its deadline, what is owed so far, the return periods and anything that needs attention.	Read-only	`books:read`
`get_vat_return_figures` Get VAT return figures	The nine boxes of one VAT return as the books stand, with Tolvi’s checks. It reads the figures only and never sends anything to HMRC.	Read-only	`books:read`

Amounts come back formatted for reading, with credits in brackets, and as integer pence in the structured result.

How do the Tolvi Books tools choose the business?

A practice reaches a client's books only through a link the business has agreed to. Ask the assistant to list your linked businesses first: each Books tool then takes that business's id, and Tolvi sends it to the API as the x-business-id header, exactly as the app does. On every call the API checks that the link is still live, that your practice has Tolvi Books and that you may use it, and limits you to what the link allows. If the business ends the link, the tools stop working for it straight away.

The Books tools need the books:read scope, and listing your linked businesses needs client_books:read.
They only read. Explaining bank lines, confirming receipts, raising and sending invoices, and VAT returns stay in Tolvi Books.

For a business's own assistant

A business owner (or anyone at the business) uses a second address, https://mcp.tolvi.co.uk/books/mcp. The assistant signs in with your Tolvi Books account, with no firm or organisation, and asks for books:read. It then reads your own business's books, so the tools don't take a business id, and listing linked businesses isn't offered. A sign-in for one address doesn't work at the other.

Read-only, whatever your role in the business: there are no tools that change your books.
It works for a person with one business in Tolvi Books. With more than one, Tolvi asks which business, and an assistant can't choose one yet.
Every call is recorded in your business's audit log as made through MCP, with the assistant's name.

How are changes confirmed?

A tool that changes something never acts on the assistant's word alone, because a model can be misled by text it reads.

Write tools are marked as destructive, so assistants ask you before calling them.
Where the assistant supports it, Tolvi asks you directly with a preview of the change, and nothing happens unless you accept.
Otherwise the first call only returns a preview. The change is made on a second call, after you've agreed.
Each change carries an idempotency key, so a repeated call can't apply it twice.

What will the MCP server never do?

Sign off a section, approve an engagement or send work back. Those stay a deliberate action by a person in the Tolvi app.
Do more than the signed-in person can. It has your role and the scopes you granted, never more.
Connect or disconnect bookkeeping software, manage webhooks or API credentials, change firm settings or billing.
In Tolvi Books: file a VAT return, link a bank or HMRC, send an invoice or reminder, take or make a payment, lock a period, change who has access to the books, or set a rule that posts on its own.
Act unrecorded. Every tool call is in the audit log as made through MCP, with the tool and the assistant's name, alongside the change it made.

How will I add it to an assistant?Coming

Connecting is coming next. When it's ready, these are the steps.

Claude. Add a custom connector with the URL https://mcp.tolvi.co.uk/mcp, then sign in to Tolvi when Claude asks and approve the scopes.
Other assistants. Any MCP client that supports remote servers over Streamable HTTP with OAuth sign-in. Give it the URL and sign in to Tolvi when it asks.
Removing it. Remove the connector in your assistant. If you leave the firm or your role changes, its access changes with it, because every call is checked as you.

To hear when connecting is ready, email support@tolvi.co.uk.