Connecting AI Tools (MCP)

Peaky speaks the Model Context Protocol (MCP), so AI tools you already use — Claude, ChatGPT, Cursor, VS Code, Gemini CLI and any other MCP-compatible client — can work with your Peaky data while you work in them. Ask your AI tool about your entities, scenarios, ledgers or transactions and it looks them up in Peaky, in your name and within your permissions.

One address connects a tool to everything you choose: the companies you belong to and, if you work at an accounting firm, the firm's clients. You connect each tool once, not once per company.

A connection is read-only unless you allow changes. With changes allowed, the tool can also create, edit and delete — build a model, change a formula, map ledgers, lay out a view — but only what your role lets you do in Peaky yourself.


Connect an AI Tool

  1. Open your profile menu, choose My account and go to the AI tab. (On the Integrations page, the AI tools (MCP) card's Connect an AI tool button opens the same tab.)

  2. Under Connect an AI tool, copy the MCP address with the copy button. It is the same for everyone in Peaky, so you can share it with colleagues: each person signs in and chooses what their own tool may reach.

  3. Pick your AI tool's tab and follow the instructions. Snippets have their own copy button.

Tab

What to do

Claude

On claude.ai or in the Claude desktop app, open Settings → Connectors, choose Add custom connector, name it Peaky and paste the address. On a Team or Enterprise plan, an owner may need to add the connector for your organization first.

ChatGPT

Turn on Developer mode in ChatGPT's settings, then create a connector with the address and OAuth as its authentication. Developer mode needs a paid ChatGPT plan.

Claude Code

Run the claude mcp add command shown, then /mcp in Claude Code to sign in

Cursor

Click Add to Cursor, or add the snippet to ~/.cursor/mcp.json

VS Code

Click Add to VS Code, or add the snippet to .vscode/mcp.json in your project

Gemini CLI

Add the snippet to ~/.gemini/settings.json, then run /mcp auth Peaky

Other

Any MCP client that supports remote servers: add a server with the address (Streamable HTTP). It signs in with OAuth, so there is no key to copy.

The server is called Peaky in every tool.

Connecting is your own choice, so it needs no integration rights — but a tool only ever reaches companies where your role has AI agents (see below).


Authorize Your AI Tool

The first time your AI tool connects, it opens Peaky in your browser. Sign in if you need to, and Peaky asks you to confirm: Authorize tool name shows which tool is asking and which account you are signed in with. Then choose what it may reach:

  • Firms — each firm you belong to, with your role there and how many companies it reaches today. A firm's admins reach every client of the firm, its users the clients assigned to them. Clients the firm adds or assigns to you later are included without authorizing again.

  • Companies — the companies you belong to yourself, one by one.

With many to choose from, a search box narrows the list, and Select all ticks everything shown in a section. If there is only one firm or company to choose, it is already ticked. Authorize stays unavailable until you pick at least one.

Only firms and companies where your role has AI agents are offered. If there are none, the screen tells you so and offers only Cancel: ask an admin of your company to give your role AI access, then connect again.

Tick Also allow it to make changes if the tool should be able to create, edit and delete as well as read. Leave it unticked for a read-only connection. The choice covers everything the tool reaches. Then click Authorize to allow it, or Cancel.

The authorization belongs to you: the tool acts as you, and sees only what you could see in Peaky yourself. Authorizing the same tool again replaces your earlier choice.

Working Across Companies

A connected tool can list the companies it reaches and works on one at a time, so ask about a company by name. A firm admin's tool lists every client of the firm, not only the ones assigned to you. When a tool reaches a single company, it uses that one without asking.


What a Connected Tool Can Do

Everything a tool reads or changes follows your role:

  • AI agents — using any AI tool with Peaky needs AI agents on your role, the same permission as the in-app assistants, in each company the tool works in. Take it away and the tool is refused in that company from its next request, with nothing to revoke by hand — even when you granted the whole firm.

  • Everything else — in each company, the tool may only use what your role there allows, and no more:

The tool can

When your role can view

List your entities

Entities

See how far the company's setup is: which steps are done, skipped, open or waiting on a sync, and what to do next

Always

List scenarios, and a scenario's version history

Scenarios

List a scenario's models and drivers, read a driver's formula, check a scenario for problems, and read its calculated results (with how each value was computed)

Models

List metrics, read their values (per month, quarter or year, overall or for one combination of dimension values), and list their aggregation groups

Metrics

List ledger groups, with how many formulas in your models use each one

Ledger groups

List ledgers — with the group each is mapped to if your role can also view Ledger groups, and its movements over the last twelve months if it can also view Transactions

Chart of accounts

Read the trial balance

Chart of accounts

Check how ledgers are mapped to ledger groups

Chart of accounts and Ledger groups

List transactions, and a ledger group's transactions

Transactions

List dimensions and cost centers

Dimensions

List your integrations with their settings, last sync and any problem to fix, what else could be connected, and each one's sync history

Integrations

List the tables your integrations synced, read their first rows, list the custom metrics defined on them, and preview a draft metric

Data

List scenario and ledger group templates

Templates

List your views, open one, compute a statement widget's numbers, and read a view's version history and its earlier versions

Your own views always; team views with Views; views shared with you

See who a view is shared with and whether it has a public link

Views you may edit

List the company's data exports and whether each is ready

Exports

List signals and read one

Signals (the integrations report also needs Integrations)

List the people in your company, to pick signal owners

Team

Search the Peaky help center

Always

Lists that belong to one entity default to your main entity; the tool can pick another one from the entity list.

Firm Tools

If you work at an accounting firm and chose the firm when you connected, the AI tool can also work across the firm's clients. It lists the firm with your role in it, and the firm tools take the firm instead of a company:

  • Your clients — the clients you work on (every client for a firm admin, the ones assigned to you for a firm user), how far each is set up, and how many of the firm's licences are in use.

  • Firm templates, when templates are enabled for your firm — list them; with changes allowed, apply one to a client as a new scenario (you need the right to create templates in that client).

  • Adding a client, with changes allowed — the tool adds the company within your licences and assigns you to it. Assigning other colleagues stays in Peaky.

  • Firm admins can also save a client's scenario as a template, rename a template or delete one.

The firm's settings, team and billing, and deleting a client, are not available to AI tools.

Offer Fewer Tools

Some AI tools limit how many tools they accept from all your connections together. To give such a tool only part of Peaky, add ?toolsets= to the end of the MCP address with the groups you want, separated by commas. For example, …/mcp?toolsets=models,dashboards offers only the model and view tools. The company and entity lists are always included.

Group

What it covers

setup

How far the company's setup is

scenarios

Scenarios, their results and versions, and scenario templates

models

Models, drivers and formulas

ledgers

Ledgers, ledger groups, the trial balance, ledger group templates and confirming the mapping

transactions

Transactions (including a ledger group's transactions), dimensions and cost centers

integrations

Integrations: status, syncing, connection links and settings

data

Synced data tables and the custom metrics defined on them

metrics

Metrics, their values and aggregation groups

members

The people in your company

firms

Your firm's clients, client creation and firm templates

dashboards

Views, their widgets, versions and sharing

exports

Data exports

signals

Signals: reading, triaging, owners and approving

help

The Peaky help center

Leave ?toolsets= out to get every group. Your role still decides what is inside each group.

Making Changes

With changes allowed, the tool also gets the tools that change things, each only when your role has the matching right:

The tool can

When your role can

Create and edit scenarios, and calculate them

Update Scenarios (create them needs Create); calculating needs update on Models

Delete a scenario (not the base scenario, and not while it is locked)

Delete Scenarios

Create a scenario from a template

Create Scenarios and Models, and view Templates

Save a scenario as a template

Create Templates, and view Models

Create, edit and delete models, drivers and formulas

Create, update or delete Models

Create, edit, move and delete ledger groups, and apply or save ledger group templates

Create, update or delete Ledger groups; Templates for templates

Confirm an entity's ledger mapping as reviewed, once its ledgers have finished syncing

Update Ledger groups

Snooze, reactivate, resolve or dismiss a signal, and set its owners

Update Signals

Approve a signal: accept a drift's recommended assumption, or map a structure signal's new ledgers

Update Signals, plus update Models for a drift or Ledger groups for new ledgers

Delete a dismissed signal for good

Delete Signals

Sync an integration (at most once an hour, as on the Integrations page) and change its settings

Update Integrations

Get a link to connect a new integration, or to reconnect one

Create Integrations for a new one, update for a reconnect

Remove an integration

Delete Integrations

Create, edit and delete custom data metrics and metric aggregation groups, and delete a metric pushed through the API

Create, update or delete Data

Rename a dimension, or turn it on or off in the breakdowns

Update Dimensions

Share a view with a colleague (to view or to edit), stop sharing it, or restore an earlier version

Views you may edit

Delete an earlier version from a view's history (never the current one)

Views you may delete

Turn a view's public link on or off, with or without a passcode

Views you may edit

Start a data export

Create Exports

Create, edit and delete views and their widgets

Your own views always; team views with the matching Views right; views shared with you for editing

Signing in to another service never happens in your AI tool: to connect an integration, the tool gives you a connection link to open in your browser, where you sign in as you would from the Integrations page. Anyone with the link can complete the connection until it expires, so share it only with whoever holds the account.

The model builder is not available to AI tools: uploading a plan, choosing its sheets, answering its questions and building the model happen on the Models page. Once your model is built, an AI tool can change its models, drivers and formulas like any other.

A finished data export is downloaded from Peaky, never through your AI tool: it holds everything in the company, including how your integrations connect.

Changes are made as you, so your colleagues see them in Peaky as yours. Most AI tools ask you before each change; deletes are marked so they always can. A connection can make up to 200 changes every ten minutes — more than that and it is paused for a few minutes, with nothing changed.

To turn changes on or off later, use Allow changes next to the tool under Connected AI tools in My account → AI (see below).

See Team & Roles for the permissions, and AI Assistants for the assistants inside Peaky.


Manage Connected Tools

Open My account from the profile menu and go to the AI tab. Connected AI tools lists every tool you have connected, with when you authorized it and when it was last used (not used yet until its first request). Reaches shows the firms — each with how many companies it covers — and the companies the tool may use; a long list folds away behind Show all.

  • Allow changes turns making changes on or off for that tool, everywhere it reaches. It applies from the tool's next request.

  • Change access opens the same choice of firms and companies as the authorize screen. Pick at least one and click Save; to cut a tool off completely, disconnect it instead.

  • Disconnect (and confirm) revokes the tool's access to everything at once; it stops working immediately.

A tool that reaches nothing any more — because you left the firms and companies you gave it, or lost AI access there — says so on its row. Change its access or disconnect it.

See Signing In & Your Account.


Older Per-Company Connections

Before, each company had its own MCP address, enabled from an MCP card on its Integrations page, and you authorized a tool once per company. That card is gone, and those addresses are being retired.

Connections made that way keep working for now. They are listed separately under Connected to one company (old address) in My account → AI, one row per tool and company, each with its own Allow changes switch and Disconnect. They stop working when the old addresses are retired: to keep using a tool, connect it again with the address under Connect an AI tool, then disconnect the old connection.