Excel - Prisme.ai

The Excel connector exposes Microsoft Excel workbooks through the Microsoft Graph API. It can be consumed two ways: as a remote MCP server that Agent Factory agents call as tools, or as a Builder app whose instructions you call directly from DSUL. It runs in the installing workspace’s own app-instance context and resolves its Microsoft credential server-side — either Azure AD client credentials (a service-account app accessing files across the tenant) or delegated OAuth (acting as a signed-in user). Agents read, write, and manipulate cells, ranges, tables, charts, named items, and pivot tables in spreadsheets hosted on OneDrive or SharePoint.

Read & write cells

Read and write cell values, formulas, and ranges with full formatting control, plus insert, clear, sort, and merge operations.

Tables, charts & pivots

Create and manipulate Excel tables, charts, named ranges, and pivot tables — including exporting a chart as an image.

Functions & recalculation

Run Excel worksheet functions and force a full workbook recalculation from an agent or automation.

Who is this for?

This connector is used by three different roles. Jump to the section that matches yours — each one is self-contained.

Agent builder

You build agents in Agent Factory and want them to work with Excel workbooks. → Agent builder tab.

Platform admin

You run the platform and want to know what one-time setup Excel needs. → Platform admin setup accordion below.

Workspace builder

You write Builder automations (DSUL) that call Excel instructions directly. → Workspace builder tab.

Prerequisites

A Microsoft 365 / Azure AD tenant with the workbooks you want to reach stored in OneDrive or SharePoint (.xlsx files only — legacy .xls is not supported).
An Azure AD application registered in that tenant (Azure portal > App registrations), with a client secret generated for it.
Microsoft Graph permissions granted to the app, with admin consent:
- Files.Read.All — read-only access to files.
- Files.ReadWrite.All — read/write access to files.
- Sites.Read.All or Sites.ReadWrite.All — for SharePoint-hosted files.
For delegated OAuth mode, the same app must have a redirect URI configured and the corresponding delegated permissions consented; for client-credentials mode, the matching application permissions are used.
Note the Application (client) ID, the client secret value, and the Directory (tenant) ID — these are pasted into the app configuration. For SharePoint files, also note the site ID.

Platform admin (Governance) — one-time platform setup

No platform-level credential. Excel follows the static-credential model: each workspace pastes its own Azure AD credentials into the app configuration, and the connector resolves them server-side. There is nothing to register centrally — no shared key, no Governance OAuth auth-config JSON.

Optionally, to let agent builders pick Excel from the capability catalog instead of pasting an MCP endpoint URL, declare it once as a named capability:

Open AI Governance > Capabilities

Create (or edit) an Excel capability.

Point it at the MCP endpoint

Set the capability’s MCP server URL to the connector’s MCP Endpoint (from the Excel app instance in the providing workspace), and set its Scope to:

context_id,agent_id,user_id

The agent_id in the scope is what lets the connector identify the calling agent.

Make it available to agent builders

Once created, the capability appears in the capability picker for agent builders in your organization. Access to the catalog follows your organization’s existing roles; there is no per-capability role grant for this connector.

Declaring the capability makes the connector available in the picker; it does not grant any Microsoft access by itself. The actual file access is governed by the Azure AD credentials and Graph permissions configured in the workspace that runs the Excel app.

Agent builder (Agent Factory)
Workspace builder (DSUL)

Agent builder

Goal: let an agent you build in Agent Factory read and write Excel workbooks through Excel MCP tools.

Before an agent can call the connector, a Workspace builder must have installed and configured the Excel app with Azure AD credentials (see the Workspace builder tab). A Platform admin may also have published an Excel capability in the catalog (see the Platform admin setup accordion above).

The connector resolves its Microsoft credential server-side — it is never exposed to the agent. Your agent is identified by the agent_id that Agent Factory injects through the capability Scope.

Get the MCP endpoint

From the workspace that runs the Excel app, copy the app instance’s MCP Endpoint URL (or use the published Excel capability if a Platform admin declared one).

Add the capability to your agent

In your agent in Agent Factory, add a capability pointing at the MCP Endpoint URL, and set its Scope to:

context_id,agent_id,user_id

The agent_id is what lets the connector identify the calling agent.

Use it

Ask the agent to work with a workbook (e.g. “read A1:C10 from this sheet” or “add a row to the Sales table”). It calls the matching Excel tool, passing the file’s itemId and — for SharePoint — its siteId.

Brief the agent in its system prompt

Wiring the capability is not enough — the agent must know the tools exist and how to address a file. Copy-pasteable starter:

You have access to the Excel MCP server (Microsoft Graph). Use it to read, write, and reshape Excel workbooks stored in OneDrive or SharePoint.
Always address a workbook by its `itemId` (the Graph drive item id). For SharePoint-hosted files, also pass `siteId` (and `driveId` if you know the specific document library). Use A1 notation for ranges (e.g. "A1:C10").
Read with getRange / getUsedRange before writing. Write values with updateRange. Use the table tools (createTable, addTableRow, applyTableFilter) for structured data, and executeExcelFunction to evaluate formulas. Recalculate with calculateWorkbook after bulk edits.

Legacy AI Knowledge agents (no native MCP picker): add the connector under Advanced > Tools > MCP and paste the MCP Endpoint URL.

Available Tools

All instructions listed in the Workspace builder tab are exposed as MCP tools with the same names and parameters. They are grouped below.

Workbook

Tool	Description
`createWorkbook`	Create a new Excel workbook.
`calculateWorkbook`	Recalculate all formulas in the workbook.

Worksheets

Tool	Description
`listWorksheets`	List all worksheets in the workbook.
`getWorksheet`	Get worksheet details.
`addWorksheet`	Create a new worksheet.
`updateWorksheet`	Rename or reposition a worksheet.
`deleteWorksheet`	Delete a worksheet.
`getUsedRange`	Get the data-containing range of a worksheet.

Ranges

Tool	Description
`getRange`	Read cell values, formulas, and formatting from a range.
`updateRange`	Write values to cells in a range.
`getCell`	Read a single cell by row/column.
`clearRange`	Clear contents and/or formatting of a range.
`insertRange`	Insert cells with a shift direction.
`deleteRange`	Delete cells with a shift direction.
`sortRange`	Sort range data.
`mergeRange`	Merge cells in a range.
`unmergeRange`	Unmerge cells in a range.

Formatting

Tool	Description
`updateFormat`	Set alignment and text wrapping.
`updateFont`	Set font properties.
`updateFill`	Set background color.
`updateBorder`	Set border styles.
`autofitColumns`	Auto-fit column widths.
`autofitRows`	Auto-fit row heights.

Tables

Tool	Description
`listTables`	List tables in the workbook.
`getTable`	Get table details.
`createTable`	Create a table from a range.
`updateTable`	Update table properties.
`deleteTable`	Delete a table.
`addTableRow`	Add a row to a table.
`updateTableRow`	Update row values.
`deleteTableRow`	Delete a row.
`addTableColumn`	Add a column.
`deleteTableColumn`	Delete a column.
`applyTableSort`	Sort a table.
`applyTableFilter`	Filter a table.
`clearTableFilter`	Clear table filters.
`convertTableToRange`	Convert a table to a normal range.

Charts

Tool	Description
`listCharts`	List charts in a worksheet.
`getChart`	Get chart details.
`addChart`	Create a chart.
`updateChart`	Update chart properties.
`deleteChart`	Delete a chart.
`setChartData`	Change a chart’s data source.
`setChartPosition`	Position a chart.
`getChartImage`	Export a chart as an image.
`updateChartTitle`	Set a chart title.
`updateChartLegend`	Configure a chart legend.

Named Items & Pivot Tables

Tool	Description
`listNamedItems`	List named ranges.
`getNamedItem`	Get a named item’s value.
`addNamedItem`	Create a named range.
`updateNamedItem`	Update a named item.
`listPivotTables`	List pivot tables.
`getPivotTable`	Get pivot table details.
`refreshPivotTable`	Refresh a pivot table.
`refreshAllPivotTables`	Refresh all pivot tables.

Functions

Tool	Description
`executeExcelFunction`	Execute an Excel worksheet function and return its result.

Output Formats

Tools accept an outputFormat argument that controls the MCP response shape:

verbose (default) — a human-readable text view of the operation, optimized for LLM consumption.
structured — machine-readable JSON in structuredContent.
both — the structured payload, with its JSON also rendered as text.

Tool Details

getRange

{
  "name": "getRange",
  "arguments": {
    "itemId": "01ABCDEF...",
    "worksheetId": "Sheet1",
    "address": "A1:C10"
  }
}

Parameter	Required	Description
`itemId`	Yes	Graph drive item id of the workbook.
`worksheetId`	Yes	Worksheet name or id.
`address`	Yes	Range in A1 notation (e.g. `A1:C10`).
`siteId`	No	SharePoint site id (for SharePoint-hosted files).
`driveId`	No	Specific document library / drive id.

updateRange

{
  "name": "updateRange",
  "arguments": {
    "itemId": "01ABCDEF...",
    "worksheetId": "Sheet1",
    "address": "A1:C2",
    "values": [
      ["Name", "Age", "City"],
      ["John", 30, "New York"]
    ]
  }
}

Parameter	Required	Description
`itemId`	Yes	Graph drive item id of the workbook.
`worksheetId`	Yes	Worksheet name or id.
`address`	Yes	Target range in A1 notation; must match the `values` dimensions.
`values`	Yes	2D array of cell values to write.
`siteId` / `driveId`	No	SharePoint targeting.

createTable

{
  "name": "createTable",
  "arguments": {
    "itemId": "01ABCDEF...",
    "worksheetId": "Sheet1",
    "address": "A1:C10",
    "hasHeaders": true
  }
}

Parameter	Required	Description
`itemId`	Yes	Graph drive item id of the workbook.
`worksheetId`	Yes	Worksheet name or id.
`address`	Yes	Source range for the table in A1 notation.
`hasHeaders`	No	Whether the first row contains column headers.

addChart

{
  "name": "addChart",
  "arguments": {
    "itemId": "01ABCDEF...",
    "worksheetId": "Sheet1",
    "type": "ColumnClustered",
    "sourceData": "A1:C10",
    "seriesBy": "Auto"
  }
}

Parameter	Required	Description
`itemId`	Yes	Graph drive item id of the workbook.
`worksheetId`	Yes	Worksheet name or id.
`type`	Yes	Chart type (e.g. `ColumnClustered`, `Line`, `Pie`).
`sourceData`	Yes	Range that supplies the chart data, in A1 notation.
`seriesBy`	No	How series are grouped: `Auto`, `Columns`, or `Rows`.

executeExcelFunction

{
  "name": "executeExcelFunction",
  "arguments": {
    "itemId": "01ABCDEF...",
    "functionName": "VLOOKUP",
    "values": ["lookupValue", "A1:C10", 2, false]
  }
}

Parameter	Required	Description
`itemId`	Yes	Graph drive item id of the workbook.
`functionName`	Yes	Excel worksheet function name (e.g. `VLOOKUP`, `SUM`).
`values`	Yes	Ordered argument list passed to the function.

Workspace builder

Goal: install the Excel app in a workspace, configure the Azure AD credential, and call Excel instructions from your automations.

Installation

Go to Apps in your workspace
Search for Excel and install it
Configure the app instance with your Azure AD credentials (see Configuration below)

Configuration

Field	Description
Azure Client ID	Azure AD Application (client) ID for Microsoft Graph. Stored as a workspace secret.
Azure Client Secret	Client secret value of the Azure AD app. Stored as a workspace secret.
Azure Tenant ID	Directory (tenant) ID (GUID).
SharePoint Site ID	Optional — default SharePoint site id for SharePoint-hosted files.
Authentication Mode	`clientCredentials` (service account, default) or `oauth` (delegated user auth).
OAuth Client ID / OAuth Client Secret	Azure AD OAuth app credentials, used only when Authentication Mode is `oauth`.
MCP Endpoint	Auto-populated on install — the URL Agent Factory agents point a capability at (see the Agent builder tab).

The connector resolves its credential server-side based on the chosen mode:

Auth mode	What you provide	Best for
Client credentials (default)	Azure Client ID + Secret + Tenant ID	Service-account access to files across the tenant; server-to-server automations with no interactive sign-in.
Delegated OAuth	OAuth Client ID + Secret (plus a per-user connect flow)	Acting as a specific signed-in Microsoft user, scoped to that user’s files.

File addressing: OneDrive files need only an itemId. SharePoint files need itemId + siteId (and optionally driveId to target a specific document library). The default siteId from the configuration is used when a call omits it.

Available Instructions

Every instruction resolves credentials from the workspace configuration.

Workbook

Instruction	Description	Returns
`createWorkbook`	Create a new Excel workbook in OneDrive/SharePoint.	`{ itemId, name, webUrl }`
`calculateWorkbook`	Force a full recalculation of all formulas in the workbook (`itemId`).	Empty (HTTP 204)

Worksheets

Instruction	Description	Returns
`listWorksheets`	List all worksheets in a workbook (`itemId`).	`{ value: [{ id, name, position, visibility }] }`
`getWorksheet`	Get one worksheet’s details by `worksheetId`.	`{ id, name, position, visibility }`
`addWorksheet`	Add a new worksheet; `name` optional.	`{ id, name, position }`
`updateWorksheet`	Rename or reposition a worksheet (`name`, `position`, `visibility`).	`{ id, name, position, visibility }`
`deleteWorksheet`	Delete a worksheet by `worksheetId`.	Empty (HTTP 204)
`getUsedRange`	Get the range that actually contains data on a worksheet.	`{ address, rowCount, columnCount, values, formulas }`

Ranges

Instruction	Description	Returns
`getRange`	Read values, formulas and formatting from `address` (A1 notation).	`{ address, rowCount, columnCount, cellCount, values, formulas, numberFormat, text }`
`updateRange`	Write a 2D `values` array into `address`.	`{ address, rowCount, columnCount }`
`getCell`	Read a single cell by `row`/`column` index.	`{ address, value, formula, text }`
`clearRange`	Clear contents and/or formatting of `address` (`applyTo`).	Empty (HTTP 204)
`insertRange`	Insert cells at `address` with a `shift` direction.	`{ address }`
`deleteRange`	Delete cells at `address` with a `shift` direction.	Empty (HTTP 204)
`sortRange`	Sort `address` by one or more `fields`.	Empty (HTTP 204)
`mergeRange`	Merge the cells in `address` (`across` optional).	Empty (HTTP 204)
`unmergeRange`	Unmerge the cells in `address`.	Empty (HTTP 204)

Formatting

Instruction	Description	Returns
`updateFormat`	Set alignment and text wrapping on `address`.	`{ address }`
`updateFont`	Set font `name`/`size`/`bold`/`italic`/`color` on `address`.	`{ address }`
`updateFill`	Set the background `color` of `address`.	`{ address }`
`updateBorder`	Set border `style`/`color`/`weight` on `address`.	`{ address }`
`autofitColumns`	Auto-fit column widths over `address`.	Empty (HTTP 204)
`autofitRows`	Auto-fit row heights over `address`.	Empty (HTTP 204)

Tables

Instruction	Description	Returns
`listTables`	List tables in the workbook (`itemId`).	`{ value: [{ id, name, range }] }`
`getTable`	Get a table’s details by `tableId`.	`{ id, name, showHeaders, showTotals, style }`
`createTable`	Create a table from `address`; `hasHeaders` optional.	`{ id, name, range }`
`updateTable`	Update table properties (`name`, `showHeaders`, `style`, …).	`{ id, name, style }`
`deleteTable`	Delete a table by `tableId`.	Empty (HTTP 204)
`addTableRow`	Append a row of `values` to a table.	`{ index, values }`
`updateTableRow`	Update a row’s `values` by `index`.	`{ index, values }`
`deleteTableRow`	Delete a row by `index`.	Empty (HTTP 204)
`addTableColumn`	Add a column (`name`, `values`) to a table.	`{ id, name, index }`
`deleteTableColumn`	Delete a column by id/index.	Empty (HTTP 204)
`applyTableSort`	Apply a sort to a table by `fields`.	Empty (HTTP 204)
`applyTableFilter`	Apply a column `filter` (`criterion`) to a table.	Empty (HTTP 204)
`clearTableFilter`	Clear the filter on a table column (or all).	Empty (HTTP 204)
`convertTableToRange`	Convert a table back into a normal range.	`{ address }`

Charts

Instruction	Description	Returns
`listCharts`	List charts on a worksheet.	`{ value: [{ id, name, type }] }`
`getChart`	Get a chart’s details by `chartId`.	`{ id, name, type, height, width }`
`addChart`	Create a chart from `sourceData` (`type`, `seriesBy`).	`{ id, name, type }`
`updateChart`	Update chart properties (size, name, …).	`{ id, name }`
`deleteChart`	Delete a chart by `chartId`.	Empty (HTTP 204)
`setChartData`	Change a chart’s data source (`sourceData`, `seriesBy`).	Empty (HTTP 204)
`setChartPosition`	Reposition a chart by anchor cells.	Empty (HTTP 204)
`getChartImage`	Export a chart as a base64 image (`width`/`height`).	`{ image }` (base64 PNG)
`updateChartTitle`	Set a chart’s title text.	`{ id, title }`
`updateChartLegend`	Configure the chart legend (`position`, `visible`).	`{ id }`

Named Items & Pivot Tables

Instruction	Description	Returns
`listNamedItems`	List named ranges in the workbook.	`{ value: [{ name, value, scope }] }`
`getNamedItem`	Get a named item by `name`.	`{ name, value, type, scope }`
`addNamedItem`	Create a named range (`name`, `reference`).	`{ name, value, scope }`
`updateNamedItem`	Update a named item’s reference/visibility.	`{ name, value }`
`listPivotTables`	List pivot tables on a worksheet.	`{ value: [{ id, name }] }`
`getPivotTable`	Get a pivot table’s details by id.	`{ id, name }`
`refreshPivotTable`	Refresh one pivot table.	Empty (HTTP 204)
`refreshAllPivotTables`	Refresh every pivot table in the workbook.	Empty (HTTP 204)

Functions

Instruction	Description	Returns
`executeExcelFunction`	Evaluate an Excel worksheet function: `functionName` + ordered `values`.	`{ value, error }`

Returns shows the shape of the operation output. Mutating operations that the Graph API answers with 204 No Content return an empty body.

DSUL Examples

Read a range

- Excel.getRange:
    itemId: "01ABCDEF..."
    worksheetId: Sheet1
    address: "A1:C10"
  output: data

Read a SharePoint-hosted range

- Excel.getRange:
    itemId: "01ABCDEF..."
    siteId: "contoso.sharepoint.com,abc-123,def-456"
    worksheetId: Sheet1
    address: "A1:C10"
  output: data

Write values

- Excel.updateRange:
    itemId: "01ABCDEF..."
    worksheetId: Sheet1
    address: "A1:C2"
    values:
      - ["Name", "Age", "City"]
      - ["John", 30, "New York"]
  output: result

Create a table from a range

- Excel.createTable:
    itemId: "01ABCDEF..."
    worksheetId: Sheet1
    address: "A1:C10"
    hasHeaders: true
  output: table

Append a row, then recalculate

- Excel.addTableRow:
    itemId: "01ABCDEF..."
    tableId: "{{table.id}}"
    values:
      - ["Jane", 28, "Paris"]
  output: row
- Excel.calculateWorkbook:
    itemId: "01ABCDEF..."
  output: recalc

Error Handling

HTTP Status	Error	Solution
401	Unauthorized	Azure credentials are missing, invalid, or expired — reconfigure the app and re-check the client secret.
403	Forbidden	The Azure AD app lacks the required Microsoft Graph permissions, or admin consent was not granted.
404	Not Found	Verify the `itemId` (and `siteId`/`driveId` for SharePoint) — the workbook, worksheet, or range does not exist.
423	Locked	The file is open in a desktop Office app; close it or wait for auto-save.
429	Rate Limited	Microsoft Graph throttled the request — back off and retry, honoring the `Retry-After` header.
500 / 503	Service error	Transient Microsoft Graph error — retry shortly.

Common Issues

“Missing Azure credentials” — The app configuration has no clientId / clientSecret / tenant. Open the Excel app instance and paste your Azure AD application credentials, then re-run. “OAuth authentication required. Please connect your Microsoft account first” — Authentication Mode is set to oauth but no delegated token exists yet for the user. Complete the Microsoft connect flow before calling Excel tools, or switch the mode to clientCredentials. “Client credentials auth failed” — Azure AD rejected the client-credentials token request (wrong tenant id, expired or wrong client secret, or the app lacks application permissions). Re-check the credential values and the granted Graph permissions. “File is locked” — The workbook is open in the desktop Excel application. Close it or wait for auto-save to release the lock. “Invalid range address” — Use A1 notation (e.g. A1:C10), not numeric row/column indices. “.xls not supported” — Only .xlsx workbooks are supported by the Graph workbook API. Convert legacy .xls files to .xlsx first.

Microsoft Graph caps workbook requests at roughly 5 million cells per call and a 25 MB file size; split very large ranges into smaller calls to avoid 429/oversize errors.

External Resources

Microsoft Graph Excel API

Official reference for the Microsoft Graph workbook (Excel) API.

Excel API best practices

Performance and session guidance for the Graph workbook API.

Graph Explorer

Test Microsoft Graph calls interactively against your tenant.

Tool Agents

Learn how Agent Factory agents consume MCP tools in Prisme.ai.

Read & write cells

Tables, charts & pivots

Functions & recalculation

​Who is this for?

Agent builder

Platform admin

Workspace builder

​Prerequisites

​Agent builder

​Brief the agent in its system prompt

​Available Tools

​Workbook

​Worksheets

​Ranges

​Formatting

​Tables

​Charts

​Named Items & Pivot Tables

​Functions

​Output Formats

​Tool Details

​getRange

​updateRange

​createTable

​addChart

​executeExcelFunction

​Workspace builder

​Installation

​Configuration

​Available Instructions

​Workbook

​Worksheets

​Ranges

​Formatting

​Tables

​Charts

​Named Items & Pivot Tables

​Functions

​DSUL Examples

​Read a range

​Read a SharePoint-hosted range

​Write values

​Create a table from a range

​Append a row, then recalculate

​Error Handling

​Common Issues

​External Resources

Microsoft Graph Excel API

Excel API best practices

Graph Explorer

Tool Agents

Who is this for?

Prerequisites

Agent builder

Brief the agent in its system prompt

Available Tools

Workbook

Worksheets

Ranges

Formatting

Tables

Charts

Named Items & Pivot Tables

Functions

Output Formats

Tool Details

getRange

updateRange

createTable

addChart

executeExcelFunction

Workspace builder

Installation

Configuration

Available Instructions

Workbook

Worksheets

Ranges

Formatting

Tables

Charts

Named Items & Pivot Tables

Functions

DSUL Examples

Read a range

Read a SharePoint-hosted range

Write values

Create a table from a range

Append a row, then recalculate

Error Handling

Common Issues

External Resources