# 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](/doc/building-a-model-from-your-financial-plan-1pIHadpOey) 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](/doc/team-roles-ORspfM4rgP) for the permissions, and [AI Assistants](/doc/ai-assistants-HKyXOM6sFm) 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](/doc/signing-in-your-account-44RV1v0Y66).


---

## 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.