MCP Workflow

The server is session-oriented. Open a workbook once, perform many operations against a sessionId, then save and close it. This avoids reparsing the file on every tool call and keeps formula evaluation state coherent.

Glossary: session

An in-memory open workbook plus its engine state, keyed by a string sessionId. Sessions are isolated from each other — two open files have separate caches, dirty sets, and dependency graphs.

Repeat the middle three steps — mutate, recalculate, read — as many times as the workflow needs before saving and closing.

Open

{
  "path": "input.xlsx",
  "sessionId": "work"
}

To create a fresh workbook instead of loading one, omit path. The server then returns a session backed by a default workbook with Sheet1. For a loaded file, inspect session.loadLosses in the response before treating the input as a complete round trip: it reports content the reader could not decode.

Mutate cells

{
  "sessionId": "work",
  "mutations": [
    { "type": "number",  "a1": "Sheet1!A1", "value": 41 },
    { "type": "formula", "a1": "Sheet1!B1", "formula": "=A1+1" }
  ],
  "recalc": true
}

recalc: true triggers a recalculation at the end of the mutation batch. Set it to false when you intend to batch multiple set_cells calls before triggering a single recalc.

A1 or zero-based — pick one

Each mutation may address the target cell as a1: "Sheet1!B2" or as sheet, row, col integers. The integer form is 0-based and matches the Formulon API. Pick one style per workflow to keep agent outputs readable.

Read

{
  "sessionId": "work",
  "range": "Sheet1!A1:B1"
}

Returns the values in the rectangle, kind-tagged. For a single cell, use formulon_get_cell instead.

Recalculate explicitly

When mutations were applied without recalc: true, trigger one explicit pass:

{ "sessionId": "work" }

through formulon_recalc_session before reading dependent values.

Find / replace

{
  "sessionId": "work",
  "query": "budget",
  "target": "both",
  "matchCase": false
}

{
  "sessionId": "work",
  "query": "budget",
  "replacement": "forecast",
  "target": "texts",
  "recalc": true
}

target can be texts, formulas, or both — useful for refactoring formula references without touching unrelated text cells.

Save

{
  "sessionId": "work",
  "outputPath": "output.xlsx"
}

formulon_save_session always writes to disk; it never returns file content inline. A .xlsb destination uses the XLSB container; every other extension uses XLSX. The write goes through a sibling temporary file and atomic rename. The destination resolves through a fallback chain:

The response's bytes field is a byte count (a number), not the file's contents. It also reports the selected container format and, when the writer dropped or downgraded content, losses. Review losses before treating the round trip as lossless. formulon_update_workbook returns the same save fields.

Omitting outputPath overwrites the original file

If the session was opened from an existing path and you call formulon_save_session without outputPath, the server silently overwrites that source file — there is no dry-run or confirmation step. A session created fresh (no path at open time) has no sourcePath to fall back to, so an omitted outputPath fails with outputPath is required for a new workbook session instead of guessing. Pass an explicit outputPath whenever you want to avoid touching the original file.

Close

{ "sessionId": "work" }

Releases the session's engine state. Sessions also expire when the server process exits, but releasing explicitly is cheaper and clearer when running long agent sessions.

One-shot helpers

Some tools combine the whole loop in a single call when the agent only needs the final result:

Tool	Effect
formulon_eval_formula	Evaluates a formula in a throwaway workbook
formulon_inspect_workbook	Opens, summarizes, and closes — no session retained
formulon_update_workbook	Loads / creates, applies mutations, recalculates, saves — no session retained

Use them when the agent does not need follow-up reads on the same workbook.

Read next

• Tools — every tool grouped by category.
• Security model — what is and is not allowed.