Skip to main content
You are helping a user connect cfo.ai to an AI client and work in their workspace. The cfo.ai MCP server exposes the same workspace tools Ari, cfo.ai’s AI finance coworker, uses. Those tools can read and change a live financial Model. You configure the MCP client. The user creates their account, signs in, sets up their plan, and approves the connection in a browser. A connection is complete only when the client lists the server and an authorized cfo.ai tool call succeeds. Every page linked here also has a Markdown version: add .md to its address, such as https://docs.cfo.ai/agents/mcp-tools.md.

​
Confirm account access

  1. Ask whether the user can sign in to app.cfo.ai. If they cannot, direct them to create or open their account there and finish setup in the browser.
  2. The workspace must have started its free trial or a plan. Until it has, every tool call answers Start the free trial in cfo.ai before using its MCP tools.
  3. Wait for the user to finish browser-only steps. Never ask for their password, verification code, payment details, or an authorization token. cfo.ai has no API keys, so there is no key to ask for.

​
Register the MCP server

The production server URL is:
For Claude Code:
For Codex:
For another client, add https://api.cfo.ai/mcp as a remote HTTP MCP server named cfoai. Claude’s desktop and web apps add it as a custom connector, and ChatGPT and Cursor have their own forms; Connect an AI tool gives the steps for each. If you cannot run a setup command, give the matching command to the user and wait for them to run it.

​
Have the user approve the connection

The user approves the connection in a browser while signed in to cfo.ai.
  • In Claude Code, restart the session if needed, open /mcp, select cfoai, and choose Authenticate.
  • In Codex, run codex mcp login cfoai.
  • In another client, follow its normal OAuth or remote-MCP sign-in flow.
The browser shows a cfo.ai page headed Connect CFO.ai. Tell the user to check that they are signed in to the cfo.ai account the client should use, then select Connect CFO.ai. The page is valid for 60 minutes. If it reports that the approval was not recorded, start the sign-in again; If sign-in fails explains each message.

​
Verify the connection and the workspace

  1. Confirm that the client lists cfoai and exposes its tools. If it does not, restart the session and check its MCP server list again.
  2. Call list_orgs. It returns the user’s workspaces, each with org_id, name, slug, and role.
  3. If the user has one workspace, tools select it automatically. If they have several, ask which one to use, and pass its ID or slug as org_id on every later call.
  4. Make one read-only call before you report success, such as inspect_pages with:

​
Understand the Model before changing it

The server sends cfo.ai’s modeling instructions when the client connects. Read them first. Then read the built-in skill that covers the work, with inspect_skills:
  • build-model before you create or change model logic, Variables, Dimensions, or saved tables.
  • build-visualizations before you add a Canvas block.
  • import-model before you rebuild a model from a workbook or an export.
List the skills with {"list": {}}, and read one with {"instructions": {"target": "build-model"}}. The signed-in person’s own skills hold the procedures they saved; read the relevant ones before substantial work. Then inspect the existing workspace with inspect_pages, inspect_table_blocks, inspect_dimension_mappings, and inspect_scenarios. The mental model:
  • A workspace contains a financial Model, Pages, Scenarios, Variables, Dimensions, and connected data.
  • Main is the primary working Scenario. Use a different Scenario when the user wants a saved alternative.
  • inspect_pages, inspect_table_blocks, inspect_dimension_mappings, and inspect_scenarios read the existing Model.
  • edit_table_blocks creates and changes saved tables, including their Variables, Dimensions, and formulas. Every model formula is written through it.
  • edit_pages, edit_dimension_mappings, and edit_scenarios change Pages, Dimension mappings, and Scenarios.
  • inspect_canvas_library and edit_canvas_blocks read the Canvas component library and create or update Canvas blocks, the charts and custom visuals on a Page.
  • Write operations apply to the user’s live Model and must match the user’s request and workspace access.

​
Shape each call as one action block

A tool with several actions takes exactly one block named for the action, with that action’s fields inside it. There is no flat action field. For example, read a saved table with inspect_table_blocks:
and set a row’s formula with edit_table_blocks:
Copy names and references, such as Gross Profit#3f2, from inspection results instead of inventing IDs. MCP tools and call shapes lists every tool, its blocks, the fields beside them, and the refusals a wrong shape gets. Create and update formulas has the full formula shapes, and Canvas blocks for agents the Canvas ones.

​
Work safely

  • Writes apply to the live Model immediately and are recorded in its changelog under the user’s name. edit_history undoes, redoes, or reverts them, so reverse a wrong change rather than patching over it.
  • Use a Scenario other than Main when the user wants to try a change without altering the current plan.
  • Connections, access changes, invitations, share links, and emails have effects outside model undo. Confirm those with the user before you make them.
  • Honor read-only and review-before-write requests. Analyze saved values without changing the Model covers answering from what is saved.
  • When a call creates or changes something, end your reply with the link the tool returned for it, exactly as printed. A link you build yourself will not open.

​
Troubleshoot

  • cfoai is missing from the client. Restart the client and check whether the server registration succeeded.
  • Browser approval fails. Confirm that the user is signed in to the intended cfo.ai account and can open the intended workspace, then start the sign-in again. In cfo.ai, Ari can list the user’s own recent sign-in attempts and why each one failed.
  • Tools report authorization errors after a previous success. Repeat the client’s sign-in flow.
  • A call answers org_id is required. The user belongs to several workspaces. Call list_orgs and pass the intended workspace as org_id.
  • A call answers you do not have access to this workspace. The signed-in account is not a member of that workspace. Check list_orgs and the account the user approved with.
  • A call answers Start the free trial in cfo.ai before using its MCP tools. The user must start the workspace’s free trial or a plan in cfo.ai.
  • A call answers rate limit exceeded for a tool. Wait and send it again. Each tool accepts up to 60 calls a minute per user and workspace; list_orgs has no limit.
  • Calls built from the client’s tool list are refused as unknown or retired shapes. The client’s tool definitions are stale. Refresh its tool list or start a new conversation, then call again.