Connect AI assistants to Ringbook

Connect ChatGPT, Claude, Codex or Cursor to Ringbook, then ask about your books in plain language. You choose which organizations the assistant can see and what it may do there.

MCP (the Model Context Protocol) is an open standard that lets AI assistants call tools and read data. Ringbook runs a hosted MCP server, so there is nothing to install. You sign in, pick the organizations and an access level for each, and the assistant finds the available tools by itself.

Choose how to connect

There are two ways to connect. Both follow the same access rules, which are described in Security model.

The server URL for both is https://backend.ringbook.io/mcp.

What you can ask

Once connected, ask the questions you would otherwise dig for:

• "Summarize my P&L for last quarter."
• "Find all invoices from vendor X."
• "Which expense account grew the most this year?"
• "Show me anything that looks like an unpaid payable."
• "Which bank accounts still have unmatched statement lines?"

Answers come only from the organizations you granted: the ledger, the chart of accounts, reports, uploaded documents, open items and bank reconciliation status. Every figure is read live when you ask.

Connect Claude (claude.ai / Claude Desktop)

Claude connects with OAuth, so you do not copy any token. You sign in and allow access.

1. Open Settings → Connectors and choose Add custom connector.
2. Enter the server URL: https://backend.ringbook.io/mcp
3. Sign in to Ringbook when prompted.
4. On the consent screen, choose which organizations to share and the access level for each (Report, Read or Write), then choose Allow access.

You can open the consent screen again later to change the organizations or the levels.

Connect ChatGPT

ChatGPT connects to Ringbook as a custom connector. Ringbook publishes standard OAuth discovery and supports dynamic client registration, so ChatGPT can register itself without a client ID or secret from you.

1. In ChatGPT, open the settings where you manage connectors or apps and add a custom connector (a remote MCP server).
2. Enter the server URL: https://backend.ringbook.io/mcp
3. Choose OAuth as the sign-in method if ChatGPT asks.
4. Sign in to Ringbook when prompted.
5. On the consent screen, choose the organizations and the access level for each, then choose Allow access.
6. Start a chat, enable the Ringbook connector for it, and ask for the organizations it can reach.

Start with Report or Read. Grant Write only when you want the assistant to stage drafts.

Connect developer tools (personal access token)

Codex, Claude Code, Cursor, scripts and any client that sends a bearer token use a personal access token. Codex needs no separate Ringbook integration and no Claude account.

1. Go to the Connect to Ring page in Ringbook and open the AI agents tab.
2. Create a token.
3. Choose which organizations it can reach and the level for each.
4. Choose an expiry (30 days, 90 days or 1 year; 90 days is the default).
5. Copy the token, which starts with rb_mcp_. It is shown only once.

Then add it to your client:

Available tools

Your assistant sees only the tools your access level allows. Read tools answer straight from your books. Write tools create things for a person to review or use: journal entries and invoices are staged as drafts, while the other creation tools act immediately. Issuing or voiding an invoice posts to the ledger, so those two run only when the organization allows direct posting. Every tool also re-checks your own live access right on each call.

Each tool, with what it does and its level, is listed here:

Every Write tool needs its own access right in the organization, checked live on each call:

The invoice read tools (list_invoices, get_invoice, get_invoice_pdf) need the invoice view right (invoices:view).

If a tool is blocked, ask the assistant to call get_my_access. It lists every tool and the specific reason each blocked one is blocked.

Export tools hand the file back directly in the normal case. Pass delivery: "download_url" to export_report or export_report_pdf to get a short-lived download link instead, for example when the file is too large to return inline.

Journal entries are draft-first; other writes create immediately

With write access, an assistant can propose an entry but cannot post it to your ledger. The entry is staged as a draft, and a person reviews and books it in Ringbook. This is the default for every organization.

Journal-writing tools stage entries as drafts for a person to review and post by default — that is the loop the demo above walks through. Other Write tools perform their named creation action immediately: they can post a Ring or reply under one, add an account, segment, customer or vendor, upload a document, or start statement extraction and reconciliation.

An organization admin can opt in to automatic posting of balanced journal entries on the Connect to Ring page, in the AI agents tab, under Journal entries from connected AI apps. Even then, the entry passes the same validation as one a person types, and an agent can never delete an entry or change its amounts or accounts. The only edit to an existing journal is set_journal_segments, which changes just the segment tag of posted lines and is recorded in the entry's history.

Invoices are draft-first too. create_invoice_draft and update_invoice_draft only create or change a draft and post nothing to the ledger. issue_invoice (permanent: it assigns the number and posts the journal) and void_invoice (posts a reversal) run only when the organization allows direct posting for connected AI apps; otherwise they refuse and point you to the document in Ringbook. An assistant should confirm with you before issuing or voiding.

Security model

Whichever way you connect, the same rules apply.

Access levels are set per organization. Each level includes everything below it.

Your live rights always win. The effective access is the lower of the level you granted and your current access rights in the app. If you leave an organization or an admin narrows your rights, the connection narrows or closes immediately. A token can never do more than you can do in the app right now.

How credentials are handled:

• Tokens are hashed at rest and shown in full once, at creation.
• Every token expires. The default is 90 days and the maximum is 1 year. The expiry is fixed at creation. To renew, revoke the token and create a new one.
• A token can carry a tool allowlist, so it can call only the tools it needs. You can edit a token's name, organizations, levels and allowlist, but not its secret or expiry.
• Organization admins have a kill switch: they can revoke any credential's access to their organization at any time.

Credits and rate limits

A few tools use organization credits. Your personal balance is touched only if the organization runs short and you have turned on personal-credit fallback in your profile.

Most other tools are free. One exception: when a document is ingested (for example through finalize_document_upload), a confident background auto-match can add a charge of about 30 credits. Failures proven to happen before any durable work, and background jobs that roll back, are refunded. A keyed IDEMPOTENCY_OUTCOME_UNKNOWN is not automatically refunded because its write may have committed, so check the result before retrying. get_credit_balance is free, so an assistant can check the balance before it spends anything.

Requests are rate-limited per token and per organization. Normal interactive use does not reach the limits.

FAQ

Can I use ChatGPT, Codex or another AI model? Yes. ChatGPT connects with OAuth as a custom connector, and Codex connects with a personal access token. Any other app works if it supports remote MCP over Streamable HTTP and either OAuth or an Authorization: Bearer header. The app sets up the connection, not the model, so available models and MCP features depend on the app. A client that supports only local STDIO servers cannot use the remote URL.

How do I check the connection? Ask the assistant to list the Ringbook organizations it can reach. In Codex, run codex mcp list first. If sign-in fails, check the token's expiry, its organization grants, and that the token's environment variable is visible to the Codex process.

Can one connection reach several organizations? Yes. A connection or token can have access to several organizations, each with its own level. The list_organizations tool shows which ones.

How do I revoke access? Delete the token or connection in your own settings. Organization admins can also revoke any credential's access to their organization. Because effective access is the lower of the grant and your live rights, removing someone's membership closes their access at once.

Will tool schemas change under my agent? Only by addition. New tools, optional parameters and response fields can appear. Existing ones are never renamed, removed or made stricter. If a breaking change is ever needed, a versioned replacement (for example search_transactions_v2) ships beside the old tool, and the old tool keeps working for at least 90 days.

What can agents not do?

• Delete anything.
• See or touch any organization or data beyond your own access rights.
• Post journal entries to the ledger by default. Journal tools stage drafts. If an admin enables automatic posting, entries still pass the same validation as a person's, and existing entries cannot be deleted or have their amounts or accounts changed (only the segment tag of posted lines can be set). Other Write tools create Rings, accounts, segments, customers, vendors and documents immediately, or start extraction and reconciliation jobs. Invoice drafts post nothing; issuing or voiding an invoice runs only when direct posting is on.

Connection management and a complete workflow

Everything about connections lives in one place: the Connect to Ring page, AI agents tab. Check it after you connect a new app and whenever something looks wrong. For credit prices and top-ups, see Credits. Company-wide settings are in Organization settings.

Tokens and connected apps

The tab has two lists you can manage yourself. Both only show what you created or connected.

A token's Status is Active, Revoked or Expired. A revoked or expired token never works again. Create a new one instead, because the secret and the expiry cannot be changed after creation.

Recent MCP calls

Organization admins also see All organization tokens (admin) below those lists. It shows every member's tokens and connected apps, with the Owner and the Last IP of each token, so you can revoke anything you do not recognise. Under it, Recent MCP calls lists the latest tool calls, newest first, with a Load more button.

Posting policy for drafts

An organization admin chooses what happens to entries that connected AI apps create. The setting is the card at the top of the AI agents tab, titled Journal entries from connected AI apps. It applies to the whole company and every app connected to it.

The same setting decides whether issue_invoice and void_invoice may run: with Stage as drafts for review they refuse. This policy is separate from Companion's Ask first and Auto modes. Write tools may be unavailable if they are not enabled on the server.

Example: reconcile a statement

A statement workflow looks like this:

1. Ask the assistant to check the credit balance and identify the organization, account and document.
2. Start the extraction and follow the job status until it finishes.
3. Review the extracted rows with the assistant (get_statement_lines).
4. Start reconciliation (150 credits).
5. Inspect the unmatched items and suggested journals.
6. Review the drafts in Ringbook.

Starting a job does not confirm that it finished or that anything was posted.

For exports, state the report type, dates, currency and format, then check the download and the figures. When a request fails, read its error and status before retrying, so you do not start a running operation twice. Check the current tool list and the credit receipt instead of assuming every tool is free.