When you connect an AI tool such as Claude or ChatGPT to Cube, it works through a set of governed calls to the Cube MCP Server. This article covers every call it can make, how read and write access differ, the rules for writing data back, and what each call costs in AI credits.
Required permission: Use MCP (Read Only) to query and read. Use MCP (Write) to write data back, build Boards and Tables, or create scenarios, workflows, and tags. Both are in the Cube AI permission group. To set up the connection, see Connect Cube to AI Apps via MCP Server.
What the AI can do on your behalf
When you ask a question, the AI tool makes one or more calls to the Cube MCP Server to gather what it needs or to build something for you. Every call is governed by your permissions. The tool names below are the calls an AI client makes against the MCP Server, useful if you are reviewing connector activity or audit logs.
Reading your data
Available with either permission level.
| What the AI does | Tool call | What you get |
|---|---|---|
| Reads your account and dimension structure | get_chart_of_accounts |
The AI learns what data exists in your model: accounts, departments, scenarios, time periods, entities, and custom dimensions. It also reads the formula behind any calculated account, so it can explain how a metric like Gross Margin % or EBITDA is derived, not just report the value. Almost every other call starts here, because dimension IDs come from this response. |
| Browses a dimension one level at a time | get_dimension_children |
The direct children of any dimension member, so the AI can walk a large hierarchy, such as a long vendor or project list, without loading everything at once. |
| Retrieves aggregated financial data | get_financial_slice_of_data |
A summary view of your data, similar to a pivot table, with the rows, columns, and filters your question implies. "Revenue by quarter, actuals versus budget" returns a grid of calculated, consolidated values. Time rollups such as YTD, QTD, and trailing twelve months are computed by the Cube engine, and multi-currency normalization and your formulas are applied before the data reaches the AI. |
| Retrieves transaction-level detail | get_drilldown_data |
Line-item records at the lowest level of detail available, with all dimension values and metadata attached. Use this for auditing a figure or finding outliers. |
| Lists and reads your Boards |
list_dashboards, get_dashboard
|
The Boards you have access to, and the full definition of any one of them: tabs, widgets, layout, and the dimensions behind each widget. This is how the AI answers "what's already on my Q3 board" and how it preserves your existing widgets before updating a Board. |
| Checks valid Board widget settings | get_widget_settings_schema |
The settings fields and permitted values for each widget type. The AI calls this before building a Board so the widgets it creates are valid, rather than guessing at configuration. |
| Reads your tags | list_tags |
Your existing tags and their members, so the AI can filter by a grouping you already use instead of rebuilding it. |
| Lists and reads your planning Tables |
list_planning_tables, get_planning_table_data
|
The Tables you have access to, and the data grid for any one of them in a given scenario: headcount rosters, opportunity lists, asset registers, including calculated and dimension-linked columns. Rows outside your Data Access Scope are excluded before the data reaches the AI. |
| Checks valid planning Table column settings | get_planning_table_schema_options |
The column types, required attributes, and format options a planning Table supports, plus your top-level dimensions for dimension-linked columns. The AI calls this before creating a Table so the schema it builds is valid, rather than guessing at column configuration. |
| Checks Cube formula syntax | get_formula_syntax |
The rules for writing Cube formulas: operators, IF and SKIP, ISCHILDOF, time functions, intersections, and TABLE_LOOKUP. The AI reads this before it drafts a calculated account with create_formula, so the formula is valid the first time. |
| Lists your source connections and imports | list_connections |
Your source system connections, each with its recent imports and scheduled-import configuration. Use this to confirm your actuals are current before running an analysis, or to find the import the AI should refresh. |
| Reads your workflows and tasks |
list_workflows, list_tasks
|
Your workflows, filterable by status, and the tasks inside any one of them with status, due date, and assignee. "What's still open on the month-end close" is answered here. |
| Reads recent changes in your Cube | get_change_history |
A log of recent changes, such as data publishes, scenario duplications, and imports, with who made each one, when, and whether it came from AI. "What changed in our forecast this week?" returns the list, with a link to each change in Cube. |
Building and writing
These calls require Use MCP (Write). Writes to scenario data and planning Tables are also subject to the checks described under How write-back works.
| What the AI does | Tool call | What you get |
|---|---|---|
| Writes updated figures back into your model | publish_data |
The AI writes values into a scenario, one figure or many at once. "Update our Q3 reforecast with the latest actuals and my revised assumptions" lands the new numbers in the target scenario. Values are written at leaf level and your formula rollups recalculate from them. Publishes land only in scenarios opened for AI write-back or created by the AI. Every write is attributed to you and flagged as AI-originated in your audit trail. |
| Creates a scenario or dimension member | create_dimension |
A new member under a parent you name, most often a new scenario. "Create a new scenario called Headcount Downside" produces a real scenario in Cube. A scenario the AI creates is automatically opened for AI write-back, so the AI can populate it without any manual setup from you. Members created outside the Scenario hierarchy get no write protection and no AI access by default. |
| Copies an existing scenario into a new one the AI can write to | duplicate_scenario |
A new scenario seeded with the leaf-level values from one you already have, rather than an empty shell. "Copy our FY27 Budget into a scenario called FY27 Downside" gives the AI a populated starting point to adjust and leaves the source scenario untouched. The copy is automatically opened for AI write-back, so no manual setup is needed. Copying runs in the background and you receive an email when it completes; the new scenario cannot be written to until then. |
| Creates a calculated account or dimension member | create_formula |
A new formula member under a parent you name, so a metric you keep rebuilding by hand becomes part of your model instead. "Add a Contribution Margin % account under Gross Profit" creates it once, and it applies across every scenario. Formula members are calculated rather than writable, so nothing can publish over them. A formula can only reference members that share its top-level dimension, and it cannot reference Time, tags, or itself. Calculation runs in the background after the member is created, so values appear shortly afterward rather than immediately. The AI can create a new formula; it cannot edit a formula you already have. |
| Builds and updates Boards |
create_dashboard, update_dashboard
|
A live Board in your Cube workspace, with tabs and widgets, or an update to one you already have. "Build a board showing this quarter's performance" produces a real Board in Cube, not a static export. You can open, share, and edit it like any Board you built yourself. An update applies the definition the AI submits, so the AI reads the Board with get_dashboard first when it needs to keep your existing widgets. |
| Creates a planning Table | create_planning_table |
A new Table with a typed column schema: text, number, date, enum, dimension-linked, and calculated columns. "Set up a headcount roster with name, department, start date, and fully loaded cost" produces a real Table in Cube. It is created empty for each scenario you name, so the AI can populate it next with write_planning_table_data. Sharing is set to Managers or All; sharing with specific users is not available through MCP. The Table itself can be created against any scenario you can write to, but data only lands in scenarios opened for AI write-back. |
| Writes data into a planning Table | write_planning_table_data |
The AI writes a dataset into a Table for a given scenario, so a headcount plan or asset schedule can be built in one pass rather than typed row by row. This replaces the full dataset for that Table and scenario: rows the AI does not resend are removed, though rows outside your Data Access Scope are always preserved. Review what an AI proposes before accepting it on a Table you rely on. The target scenario must be open to AI write-back. |
| Creates tags | create_tag |
A new tag that groups dimension members for reporting. "Create a tag grouping our top ten revenue accounts" adds a new grouping you can filter on. A tag sits outside the account hierarchy and does not change any rolled-up total. All members of a tag must come from the same top-level dimension. |
| Drafts workflows and tasks |
create_workflow, create_task
|
A new workflow, or a new task inside one. "Set up a close checklist for October" builds the structure for you. Nothing goes live on its own: a new workflow is created as Not Started with you as owner, and a new task is created as a draft with no assignee and no due date unless you name one. You review and assign before anyone is notified. Running workflows cannot be cancelled or cleared through MCP. |
| Refreshes actuals from a source system | initiate_import |
Starts an import for one of your existing connections, into the scenario and date range you name, reusing the mapping and dimension defaults from that connection's last successful import. "Pull in yesterday's actuals from NetSuite before we look at the variance" refreshes the data rather than working from a stale load. The values that land come from your source system through your own mapping rules, not from the AI. |
Session and setup
These calls carry no financial data. They appear in connector activity because the AI uses them to establish which Cube company it is working in.
| What the AI does | Tool call | What you get |
|---|---|---|
| Lists the companies you can access | list_companies |
The Cube companies your login reaches. If you have access to more than one, the AI uses this to ask which you mean. |
| Sets the active company | select_company |
Points the rest of the conversation at one company, so every later call reads and writes in the right place. Worth checking first if an AI returns figures you do not recognize. |
Every one of these runs through your Data Access Scope. The AI can only read or build from data you are authorized to see in Cube.
AI credits
Calls from an AI tool to the Cube MCP Server use AI credits from your company's shared pool, based on what the call does:
| Call type | Tool calls | Credits |
|---|---|---|
| Retrieves financial data |
get_financial_slice_of_data, get_drilldown_data
|
5 per call |
| Builds or writes anything in Cube | Every call under Building and writing | 125 per call |
| Everything else: session and setup, and reading your structure, Boards, Tables, tags, formula syntax, workflows, connections, and change history | Every other call under Reading your data and Session and setup | Free |
The AI tool decides how many calls to make. A focused question may take a few data calls, while a broad request, such as building a board deck, can take dozens. For example, a prompt that makes 20 data calls and publishes one set of figures uses (20 × 5) + 125 = 225 credits. All MCP usage appears under the MCP tier on the Usage page. See How AI Credits Work.
Read access and write access
MCP access comes in two permission levels, granted by an admin. They determine what the AI can do on your behalf:
- Use MCP (Read Only): the AI can query and retrieve data, drill down, read your planning Tables, list and read Boards, read your tags, see your source connections and import history, read your change history, and read your workflows and tasks, all within your Data Access Scope. It cannot change anything.
-
Use MCP (Write): everything read access can do, plus writing data back with
publish_data, writing into planning Tables, creating scenarios and dimension members, building and updating Boards, drafting workflows and tasks, refreshing actuals from a source connection, and creating tags, subject to the write rules below.
A few things to know about write access:
- Use MCP (Write) can only be held by a user who already has write capability in Cube, meaning a Finance or Admin user. It cannot be granted to a Business user.
- Having permission to publish inside the Cube interface does not by itself grant MCP write access. The two are controlled separately.
- When your organization is upgraded, everyone who previously held the single MCP permission is migrated to Use MCP (Read Only). No user is automatically given write access.
- By default, Use MCP (Write) is on for Admin and Finance users and off for Business users. An admin can adjust this or create custom user groups. See Manage Cube AI Permissions.
How write-back works
Write-back is built so an AI can never silently overwrite a scenario you rely on. Two rules govern where an AI can write:
- An AI can always write to a scenario it created, because scenarios an AI creates are automatically opened for AI write-back.
- An AI can write to an existing scenario only if a person has explicitly opened that scenario for AI write-back, by turning on its "AI" write protection setting.
New scenarios are the AI's sandbox. Existing scenarios stay your data, writable by an AI only on your explicit invitation. The "AI" setting is off by default on every scenario except those an AI created.
Every write passes four checks. Each write is checked, on every call, against all four of these. If any check fails, nothing is written:
- The user holds Use MCP (Write).
- The user has the underlying write capability in Cube (Finance or Admin).
- The write is within the user's Data Access Scope.
- The target scenario is open to AI write-back, or was created by the AI.
Because access is re-checked on every call, if an admin removes a user's write access, the change takes effect on that user's next write. Their read access keeps working.
Separately from these checks, every call, whether a read or a write, needs enough AI credits to cover its cost. If your company's balance is too low, the call is blocked and nothing is read or written.
Open an existing scenario for AI write-back. To let an AI write to a scenario that already exists, a person turns on the "AI" write protection setting for that scenario. This is a deliberate action, and an AI cannot turn it on for you.
- Open the scenario's settings in Cube.
- Set its write protection value to "AI".
- Save. The AI can now write to that scenario, subject to the other three checks.
The "AI" setting and time-based write protection work independently. A scenario can be open to AI write-back and still have specific time periods locked. A write to a locked period, or to a period whose data is routed elsewhere by a scenario lifecycle rule, is denied.
When a write is blocked. A blocked write returns a clear reason and never reveals data outside your access. The most common reason is that the target scenario is not open to AI write-back, and the message names the fix: open that scenario for AI, or have the AI create a new scenario to write into. Other reasons include not holding write access, targeting data outside your Data Access Scope, targeting a locked or lifecycle-routed period, or your company running out of AI credits.
Things to keep in mind
- AI agents can build and update Boards, write updated figures back into scenarios opened for AI, populate planning Tables, create new scenarios and dimension members, draft workflows and tasks, refresh actuals from a configured source connection, and create tags, when the user holds Use MCP (Write). They cannot rename or restructure existing dimensions, edit existing formulas or tags, delete Boards or other assets, cancel or clear a running workflow, assign a task to someone, change anyone's permissions, or write to your connected source systems through Cube.
- An AI writes data only to scenarios that are opened for AI write-back or that the AI created. It cannot write to a scenario on its own initiative, and it cannot enable AI write-back on a scenario for you. Every write is attributed to the user who made it and flagged as AI-originated in your audit trail, within the same Data Access Scope as any read.
- Data calls and writes use your company's AI credits. Ask focused questions to keep usage down, and check the MCP tier on the Usage page to see how much your AI tools are using.
Troubleshooting
- If an AI reports that it cannot write to a scenario, the target scenario is almost always not open to AI write-back. Open the scenario in Cube and set its write protection value to "AI", or have the AI create a new scenario to write into.
- If the AI reports that "Your company has run out of Cube AI credits," your company's balance is too low for that call. Setup calls still work, so the connection stays up. A user with Administer AI can add credits from the Usage page, then ask the AI to try again. See What Happens When You Run Out of AI Credits.
- For connection problems, see Connect Cube to AI Apps via MCP Server.