## Who is this for? This connector is used by four different roles. Jump to the section that matches yours; each one is self-contained. You build agents in **Agent Creator** and want them to browse SharePoint sites, read files and query lists. → *Agent builder* tab. You want SharePoint documents indexed and searchable semantically, kept up to date. → *Knowledge base (sync)* tab. You run the platform and set up the shared Microsoft Entra OAuth client once for everyone. → *Platform admin setup* accordion below. You write Builder automations (DSUL) that call SharePoint operations directly. → *Workspace builder* tab. ## Prerequisites (Microsoft side) * A **Microsoft 365 / SharePoint Online** tenant, and an **Azure / Microsoft Entra ID** tenant where you can register an application (or a maintainer who already did). * An **app registration** in [Microsoft Entra ID](https://entra.microsoft.com) (Azure portal → **App registrations**), with a **client secret** created under **Certificates & secrets**. * **Microsoft Graph delegated permissions** granted on the app (for the per-user OAuth modes), covering the resources you intend to use: * Sites & files: `Sites.Read.All` (or `Sites.ReadWrite.All` for create/update/move), `Files.Read.All` (or `Files.ReadWrite.All`) * Directory (access-aware RAG): `User.Read`, `GroupMember.Read.All` (optional) * Sign-in / identity: `openid`, `profile`, `offline_access` * For the **application (client-credentials)** mode instead, grant the equivalent **application** permissions (e.g. `Sites.Read.All`, `Files.Read.All`) and have a Global Administrator grant admin consent. The OAuth scopes requested by default are: ```text theme={null} offline_access https://graph.microsoft.com/Sites.Read.All https://graph.microsoft.com/Files.Read.All https://graph.microsoft.com/User.Read ``` **Goal:** two one-time tasks: (1) configure the shared **central Microsoft Entra OAuth client** so every workspace lets its users sign in with their own Microsoft account, and (2) expose SharePoint as a reusable **capability** in AI Governance so agent builders can pick it without pasting endpoint URLs. ## 1. Configure the connector In [Microsoft Entra ID](https://entra.microsoft.com) → **App registrations > New registration**, register a **Web** application. Add a **Redirect URI** pointing at the core workspace callback: ```text theme={null} /workspaces//webhooks/oauthCallback ``` (e.g. `https://api.studio.prisme.ai/v2/workspaces/7oQvI6Q/webhooks/oauthCallback` on production). Microsoft Entra rejects redirect URIs that contain a colon in the path, so use the **raw workspace id** of the core SharePoint workspace (``, e.g. `7oQvI6Q`), **not** the `slug:sharepoint-next` form used by other connectors. Copy the exact URI from the connector's configuration app, which renders it for you. Add the Microsoft Graph **delegated** permissions listed in *Prerequisites*, create a **client secret** under **Certificates & secrets**, and note the **Application (client) ID**, the **secret value**, and the **Directory (tenant) ID** (or use `common` / `organizations` for multi-tenant). Open the central `sharepoint-next` workspace and launch its **Configuration app**: `/apps/sharepoint-next` (e.g. `https://studio.prisme.ai/apps/sharepoint-next`), also linked as `Configuration app` on the installed instance. Switch to the maintainer view and follow the in-app instructions to paste the **Client ID**, **Client Secret**, **Tenant** and (optionally) scopes; the app stores them in the core workspace's secrets for you. Do not edit Studio's raw Secrets by hand. These credentials stay in the `sharepoint-next` workspace and are never exposed to tenants or end users; token exchange is proxied through the core `centralTokenExchange` webhook so the client secret never leaves the core workspace. Each consuming workspace selects auth mode **`oauthCentral`** in the connector configuration app (no client id/secret to enter on their side). Their users then just click **Connect**. ## 2. Declare the capability in AI Governance Generic connectors (broad tool surfaces meant to be shared across many agents, like SharePoint) are best exposed as a named **capability** in AI Governance. Agent builders then enable that capability on their agents instead of pasting a raw MCP endpoint. Create (or edit) the **SharePoint** capability. Set the capability's MCP server URL to the connector's **MCP Endpoint**, and set its **Scope** to: ```text theme={null} context_id,agent_id,user_id ``` The `agent_id` in the scope is what lets the connector identify and authorize the calling agent. Once created, the capability appears in the capability picker for agent builders in your organization, who enable it on their agents. Access to the catalog follows your organization's existing roles; there is no per-capability role grant. From an agent that has the capability, in a workspace configured for `oauthCentral`, trigger any tool. The user is prompted to connect once (Microsoft sign-in); subsequent calls reuse the stored token transparently and refresh it automatically. The connector's configuration app also offers a one-click **Add to catalog** button (workspace owner / admin only) that publishes the SharePoint capability to the organization-wide Capabilities catalog for you, the easiest way to expose it to agent builders without hand-editing Governance. Declaring the capability makes the connector **available**; it does not by itself authorize a specific agent. This connector follows the **tenant-context model**: which agents may actually call it is gated per-workspace by the **authorized-agents allowlist** in the configuration app (see the *Workspace builder* tab). There is also **no OAuth auth-config JSON** to attach in Governance: connect / status / disconnect are handled by the connector's own webhooks, wired automatically. *** ## Agent builder **Goal:** let an agent you build in Agent Creator browse SharePoint sites, read and manage files, query lists, and check permissions through MCP tools. Before an agent can call the connector, a *Workspace builder* must have installed and configured the SharePoint app in a workspace (see the *Workspace builder* tab), and, for the central OAuth mode, a *Platform admin* must have provisioned the shared Microsoft Entra OAuth client (see the *Platform admin setup* accordion above). This connector runs in the **tenant app-instance context**: your agent is authorized two ways at once: it is identified by the `agent_id` that Agent Creator injects through the capability *Scope*, and that agent must appear in the connector's **authorized-agents allowlist** (managed in the configuration app). The Microsoft Graph access token itself is resolved server-side from the configured auth mode. There are two ways to wire it up. Pick based on how much isolation you need. ## Option A: Enable the shared capability from the catalog The fastest path: a *Platform admin* has already published a **SharePoint** capability (see the *Platform admin setup* accordion above, §2), so you just pick it from the catalog. A workspace owner can publish it in one click with the config app's **Add to catalog** button. Open the agent you want to extend and go to its capabilities / tools. Browse the capability catalog, select **SharePoint**, and enable it. The MCP endpoint URL and the *Scope* (`context_id,agent_id,user_id`) are already wired by the admin: nothing to paste, and the shared instance accepts every agent, so there is no allowlist step on your side. On the first tool call, an unconnected user is prompted to sign in; Agent Creator surfaces a `connect_url`. Application (`clientCredentials`) and `accessToken` modes need no per-user sign-in. Convenient, but your agent runs against a **shared, platform-managed instance**: its Microsoft credentials are owned by someone else and the instance accepts every agent that is granted the capability. Prefer Option B for anything beyond quick experiments. ## Option B: Run it from your own workspace (recommended) For production agents, install the connector in **your own workspace** and point the agent at *that* workspace's MCP endpoint. **Prefer this mode for security.** Because the MCP runs in *your* app-instance context, the Microsoft credentials, the per-user OAuth tokens and the authorized-agents allowlist are all **scoped to your workspace**, not shared platform-wide. You decide exactly which agents may call it and which Microsoft account / auth mode backs them, and a misconfiguration elsewhere can never expose your SharePoint content. The shared catalog capability (Option A) is a broad surface many agents can reach; your own workspace is an isolated, least-privilege boundary. Follow the *Workspace builder* tab: install **SharePoint** in your workspace, open its **Configuration app**, choose the auth mode and connect a Microsoft account. In that workspace's config app, open **Authorized agents** and tick your agent (the **Install capability** button does this for you). In your agent, add a capability pointing at **your workspace's MCP Endpoint** URL, and set its **Scope** to: ```text theme={null} context_id,agent_id,user_id ``` The `agent_id` is what lets the connector identify and authorize your agent; without it, every call is rejected with an explicit "agent could not be identified" message. This *Scope* is separate from the Microsoft Graph OAuth scopes. On the first tool call, the user is prompted to sign in (or uses **Connect** in the config app). ## Brief the agent in its system prompt Whichever option you pick, wiring the capability is not enough: the agent must know the MCP exists and when to use it. Copy-pasteable starter: ```text theme={null} You have access to the SharePoint MCP server (tools: sites, drives, items, search, permissions, lists, directory, workbook, documents). Each tool takes an `action` argument. Use it whenever the user asks about SharePoint sites, document libraries, files and folders, SharePoint lists, sharing permissions, or who can access a document. To read a file, pick the tool by format: a Word `.docx` file with the `documents` tool, an Excel `.xlsx` file with the `workbook` tool, a text file (`.txt`, `.csv`, `.md`, `.json`) with `items` `getContent`, and any other file (PDF, PowerPoint, images) with `items` `attachToChat`, which asks the user to attach it to the conversation. Never try to decode file bytes yourself. Prefer calling a tool over guessing, and confirm with the user before any write or destructive action (create, update/move, copy, delete, invite, create link, add/create worksheet or table). ``` **Legacy AI Knowledge agents** (no native MCP picker): add the connector under **Advanced > Tools > MCP** and paste the **MCP Endpoint** URL. The agent still has to be allowlisted in the config app and its identity propagated so the connector can read its `agent_id`. **Restricting to read-only (least privilege).** SharePoint tools cover both reads and writes (create folders, rename, move, copy, delete, share, edit list items and Excel cells; the connector never uploads file content). The default scopes depend on the OAuth client: with your own Microsoft Entra app, the connector requests **read-only** scopes (`Sites.Read.All`, `Files.Read.All`) unless you widen the **Scopes** field; with the platform's central client, it requests `Sites.ReadWrite.All` and `Files.ReadWrite.All`. To keep the connector read-only, set the read scopes (the **Read-only preset** of the configuration app): ```text theme={null} offline_access https://graph.microsoft.com/Sites.Read.All https://graph.microsoft.com/Files.Read.All https://graph.microsoft.com/User.Read ``` Any write attempt is then rejected by Microsoft Graph with `403 Forbidden`. The scope is set at the workspace level (a workspace editor can widen it); for a hard guarantee, use an Entra app limited to read permissions. ## Available Tools Each tool takes an `action` argument selecting the concrete operation, plus the per-action parameters. | Tool | Description | | - | - | | `sites` | SharePoint sites discovery. Actions: `search`, `get`, `getRoot`, `listSubsites`. | | `drives` | Document libraries (drives) of sites and OneDrive. Actions: `listForSite`, `getSiteDefault`, `get`, `getMine`, `listMine`. | | `items` | Files & folders (driveItems): browse, read text files, offer any other file for attachment to the conversation. Actions: `listMyRootChildren`, `listMyChildrenByPath`, `listChildren`, `listRootChildren`, `changes`, `get`, `getContent`, `attachToChat`, `createFolder`, `update`, `delete`, `copy`, `thumbnails`, `versions`. | | `search` | Microsoft Search across SharePoint / OneDrive. Action: `query`. | | `permissions` | Sharing & permissions on driveItems (access-aware RAG). Actions: `list`, `get`, `invite`, `createLink`, `delete`. | | `lists` | SharePoint lists and list items. Actions: `listForSite`, `get`, `listItems`, `getItem`, `createItem`, `updateItemFields`, `deleteItem`. | | `directory` | Azure AD users & groups: resolve identities and group membership. Actions: `getUser`, `userMemberOf`, `checkUserMemberGroups`, `getGroup`, `groupMembers`. | | `workbook` | Read & write Excel `.xlsx` workbooks **natively** via the Microsoft Graph Excel API: no download, no OCR; cells are returned as structured values. Target a file by `driveId` + `itemId`. Actions: `listWorksheets`, `usedRange`, `getRange`, `listTables`, `listTableRows`, `updateRange`, `addTableRow`, `addWorksheet`, `createTable`, `executeFunction`. | | `documents` | Read the content of Word `.docx` documents **natively**: no external extraction service, no OCR; parses the OOXML in-process. Target a file by `driveId` + `itemId`. Actions: `getText`, `getStructure`. | ## Output Formats Every tool accepts an `outputFormat` argument that controls the MCP response shape: * **`verbose`** (default): a human-readable text view, optimized for LLM consumption. * **`structured`**: concise machine-readable JSON in `structuredContent`. * **`both`**: the structured payload, with its JSON also rendered as text. ## Tool Details ### sites ```json theme={null} { "name": "sites", "arguments": { "action": "search", "search": "marketing", "top": 10 } } ``` | Parameter | Required | Description | | - | - | - | | `action` | Yes | One of `search`, `get`, `getRoot`, `listSubsites`. | | `siteId` | For get/listSubsites | SharePoint site id (`hostname,siteCollectionId,siteId`). | | `search` | For search | Keyword to match sites; use `*` to list all. | | `top` / `select` | No | OData `$top` / `$select`. | ### drives ```json theme={null} { "name": "drives", "arguments": { "action": "listForSite", "siteId": "contoso.sharepoint.com,abc-123,def-456" } } ``` | Parameter | Required | Description | | - | - | - | | `action` | Yes | One of `listForSite`, `getSiteDefault`, `get`, `getMine`, `listMine`. | | `siteId` | For listForSite/getSiteDefault | SharePoint site id. | | `driveId` | For get | Drive (document library) id. | | `select` | No | OData `$select`. | ### items ```json theme={null} { "name": "items", "arguments": { "action": "listChildren", "driveId": "b!xyz...", "itemId": "01ABCDEF...", "top": 50 } } ``` | Parameter | Required | Description | | - | - | - | | `action` | Yes | One of `listMyRootChildren`, `listMyChildrenByPath`, `listChildren`, `listRootChildren`, `changes`, `get`, `getContent`, `attachToChat`, `createFolder`, `update`, `delete`, `copy`, `thumbnails`, `versions`. | | `driveId` | All actions except `listMyRootChildren`, `listMyChildrenByPath`, and `attachToChat` by `path` | Drive id. | | `itemId` | For get/getContent/attachToChat/update/delete/copy/thumbnails/versions/listChildren | DriveItem id. | | `path` | For listMyChildrenByPath; optional for attachToChat | Path in the signed-in user's own OneDrive, without a leading slash (for example `Documents/Reports`). OAuth modes only. | | `parentItemId` | For createFolder | Parent folder item id. | | `top` / `select` / `orderby` / `expand` / `skiptoken` | No | OData query options and pagination. | | `body` | For createFolder/update/copy | JSON body, e.g. `createFolder` → `{ name, folder: {}, "@microsoft.graph.conflictBehavior" }`; `copy` → `{ parentReference, name }`. | ### items: reading a file's content Pick the reading path by file format: | Format | Tool and action | What the agent receives | | - | - | - | | Word `.docx` | `documents` `getText` (or `getStructure`) | The full plain text, capped at about 200 KB | | Excel `.xlsx` | `workbook` (`listWorksheets`, then `usedRange` or `getRange`) | Cell values as structured data | | Text (`.txt`, `.csv`, `.md`, `.json`, `.html`, `.xml`…) | `items` `getContent` | The decoded text, capped at about 200 KB | | PDF, PowerPoint, images, other binaries | `items` `attachToChat` | An attachment offer that the user approves in the chat | `getContent` decides from the file's metadata before downloading anything: a text file comes back as text, and any other file comes back as the same attachment offer as `attachToChat`, never as raw bytes. `attachToChat` never downloads the file. It returns a standard MCP `resource_link` whose `uri` is the file's SharePoint web link. Agent Creator then asks the user to approve the attachment; once approved, the file is fetched server-side from its pre-signed download link and indexed in the conversation, exactly like a file the user dropped in the chat. The agent then searches it like any conversation document. Size limits: * PDF, PowerPoint and other documents: up to the chat upload limit (`attachment_direct_max_bytes`, 100 MB by default). * Images: 4 MB by default (`attachment_fetch_max_bytes`), because an image is copied into the conversation before the model reads it. Above the limit, the attachment is refused and the agent should share the file's SharePoint link (`webUrl`, from `items` `get`) instead. A folder cannot be attached. For a complete agent built on these reading paths, with the canvas for producing files, follow the [Office 365 agent tutorial](/resources/tutorials/office-365-agent). ### lists ```json theme={null} { "name": "lists", "arguments": { "action": "listItems", "siteId": "contoso.sharepoint.com,abc-123,def-456", "listId": "b6c8...", "expand": "fields" } } ``` | Parameter | Required | Description | | - | - | - | | `action` | Yes | One of `listForSite`, `get`, `listItems`, `getItem`, `createItem`, `updateItemFields`, `deleteItem`. | | `siteId` | Yes | SharePoint site id. | | `listId` | For get/listItems/getItem/createItem/updateItemFields/deleteItem | SharePoint list id. | | `itemId` | For getItem/updateItemFields/deleteItem | List item id. | | `expand` | No | OData `$expand`; use `fields` to get column values. | | `select` / `top` / `filter` | No | OData query options. | | `body` | For createItem/updateItemFields | `createItem` → `{ fields: { : } }`; `updateItemFields` → `{ : }`. | ### permissions ```json theme={null} { "name": "permissions", "arguments": { "action": "list", "driveId": "b!xyz...", "itemId": "01ABCDEF..." } } ``` | Parameter | Required | Description | | - | - | - | | `action` | Yes | One of `list`, `get`, `invite`, `createLink`, `delete`. | | `driveId` | Yes | Drive id. | | `itemId` | Yes | DriveItem id. | | `permId` | For get/delete | Permission id. | | `body` | For invite/createLink | `invite` → `{ recipients, roles, requireSignIn, sendInvitation }`; `createLink` → `{ type, scope }`. | ### workbook Read & write the cells of an Excel `.xlsx` file natively via the Microsoft Graph Excel API: no download, no OCR. ```json theme={null} { "name": "workbook", "arguments": { "action": "usedRange", "driveId": "b!xyz...", "itemId": "01ABCDEF...", "worksheetId": "Sheet1" } } ``` | Parameter | Required | Description | | - | - | - | | `action` | Yes | One of `listWorksheets`, `usedRange`, `getRange`, `listTables`, `listTableRows`, `updateRange`, `addTableRow`, `addWorksheet`, `createTable`, `executeFunction`. | | `driveId` | Yes | Drive id containing the `.xlsx` file. | | `itemId` | Yes | DriveItem id of the `.xlsx` file. | | `worksheetId` | For usedRange/getRange/updateRange | Worksheet id or name. | | `address` | For getRange/updateRange | A1 range address, e.g. `"A1:D50"` or `"Sheet1!A1:D50"`. | | `tableId` | For listTableRows/addTableRow | Table id or name. | | `functionName` | For executeFunction | Excel function name, e.g. `"vlookup"`, `"sum"`, `"today"`. | | `top` / `select` | No | Query options (`listTableRows` `top`, OData `$select`). | | `body` | For write actions | `{ values: [[...], [...]] }` (updateRange / addTableRow), `{ name }` (addWorksheet), `{ address, hasHeaders }` (createTable), or the function's named arguments (executeFunction, e.g. `{ values: [[...]] }`). | `addWorksheet`, `createTable` and `executeFunction` evaluate / mutate the workbook server-side. `executeFunction` returns `{ value }`, the evaluated result of the Excel function. ### documents Read the content of a Word `.docx` file natively: the file is downloaded and its OOXML parsed in-process (no external extraction service, no OCR). ```json theme={null} { "name": "documents", "arguments": { "action": "getText", "driveId": "b!xyz...", "itemId": "01ABCDEF..." } } ``` | Parameter | Required | Description | | - | - | - | | `action` | Yes | `getText`: full plain text (paragraphs + table cells), capped \~200 KB, best for RAG / reading; or `getStructure`: the element tree (paragraphs with style/runs/formatting, tables with rows/cols/headers/cells) plus metadata and the full text. | | `driveId` | Yes | Drive id containing the `.docx` file. | | `itemId` | Yes | DriveItem id of the `.docx` file. | | `includeContent` | No (getStructure only) | Include per-element text/runs (default `true`). Ignored by `getText`. | | `maxContentLength` | No (getStructure only) | Max characters of text per element (`0` = no per-element cap). | ## Workspace builder **Goal:** install the connector in a workspace, configure authentication and the agent allowlist, and call SharePoint operations from your automations. ## Installation 1. Go to **Apps** in your workspace 2. Search for **SharePoint** and install it 3. Open the **Configuration app** (the link auto-populated on install) to choose the auth mode, provide credentials, connect, and allow the agents that may call the connector ## Configuration | Field | Description | | - | - | | **Configuration app** | Auto-populated on install; open this link to configure authentication (mode + credentials), connect a Microsoft account (OAuth modes), and manage the authorized-agents allowlist. | | **Microsoft Graph API version** | `v1.0` (default) or `beta`. | The configuration app drives everything; the app instance itself has no per-field credential form. From it you pick one of: | Auth mode | What you provide | Best for | | - | - | - | | `oauthCentral` | Nothing; just click **Connect** | Workspaces on a platform where the admin set up the central client | | `oauth` | Your own Entra **Application (client) ID + Secret** (+ tenant; redirect URI `/workspaces//webhooks/oauthCallback`) | You manage your own Microsoft Entra OAuth app | | `clientCredentials` | Entra **client ID + secret + tenant** with admin-consented **application** Graph permissions | Server-to-server / back-office, content indexing, no interactive sign-in | | `accessToken` | A pre-minted Microsoft Graph **access token** | Short-lived / caller-managed tokens | Microsoft Entra rejects a colon in the redirect URI path, so for the `oauth` mode use your workspace's **raw id** (``) in the redirect URI, not the `slug:` form. The configuration app shows the exact URI to register. Credentials are provisioned into the workspace's Secrets by the `onInstall` flow and resolved server-side. The agent allowlist (**Authorized agents**) gates which Agent Creator agents may call the MCP endpoint; see the *Agent builder* tab. ## Available Instructions Every instruction resolves credentials from the workspace configuration. Operations are grouped by SharePoint resource; the MCP server exposes the same operations behind the nine entity tools (see the *Agent builder* tab). Site ids use the `hostname,siteCollectionId,siteId` format. ### Sites | Instruction | Description | Returns | | - | - | - | | `searchSites` | Search sites across the tenant; `search` = keyword (`*` for all). | `{ value: [{ id, name, webUrl, displayName }] }` | | `getSite` | Get a site by `siteId`. | A site resource `{ id, displayName, webUrl, … }`. | | `getRootSite` | Get the tenant root site. | A site resource. | | `listSubsites` | List subsites of `siteId`. | `{ value: [ site ] }` | ### Drives | Instruction | Description | Returns | | - | - | - | | `listSiteDrives` | List the document libraries of a `siteId`. | `{ value: [{ id, name, driveType, webUrl }] }` | | `getSiteDefaultDrive` | Get the default document library of a `siteId`. | A drive resource. | | `getDrive` | Get a drive by `driveId`. | A drive resource `{ id, name, quota, … }`. | | `getMyDrive` | Get the signed-in user's OneDrive (OAuth modes). | A drive resource. | | `listMyDrives` | List the signed-in user's drives (OAuth modes). | `{ value: [ drive ] }` | ### Items (files & folders) | Instruction | Description | Returns | | - | - | - | | `listChildren` | List children of a folder (`driveId`, `itemId`). | `{ value: [ driveItem ], "@odata.nextLink" }`; each item carries `@microsoft.graph.downloadUrl`. | | `listRootChildren` | List children of the drive root (`driveId`). | `{ value: [ driveItem ] }` | | `getItem` | Get a driveItem (`driveId`, `itemId`). | A driveItem `{ id, name, size, file, folder, "@microsoft.graph.downloadUrl" }`. | | `createFolder` | Create a folder under `parentItemId`; `body` = `{ name, folder: {}, "@microsoft.graph.conflictBehavior" }`. | The created driveItem. | | `updateItem` | Rename/move an item (`itemId`); `body` = changed fields / `parentReference`. | The updated driveItem. | | `deleteItem` | Recycle an item (`driveId`, `itemId`). | Empty (HTTP 204). | | `copyItem` | Copy an item asynchronously; `body` = `{ parentReference, name }`. | Empty (HTTP 202 Accepted, `Location` monitor URL). | | `getThumbnails` | List thumbnails for an item. | `{ value: [{ id, small, medium, large }] }` | | `listItemVersions` | List versions of an item. | `{ value: [{ id, lastModifiedDateTime, size }] }` | ### Lists | Instruction | Description | Returns | | - | - | - | | `listSiteLists` | List the lists of a `siteId`. | `{ value: [{ id, displayName, list }] }` | | `getList` | Get a list (`siteId`, `listId`). | A list resource. | | `listListItems` | List items of a list; use `expand=fields` for column values. | `{ value: [ listItem ] }` | | `getListItem` | Get a list item (`siteId`, `listId`, `itemId`). | A listItem resource `{ id, fields }`. | | `createListItem` | Create a list item; `body` = `{ fields: { : } }`. | The created listItem. | | `updateListItemFields` | Update column values; `body` = `{ : }`. | The updated fields. | | `deleteListItem` | Delete a list item. | Empty (HTTP 204). | ### Search & permissions | Instruction | Description | Returns | | - | - | - | | `searchQuery` | Microsoft Search; `body` = `{ requests: [{ entityTypes, query: { queryString }, from, size }] }`. | `{ value: [{ hitsContainers: [{ hits: [...] }] }] }` | | `listPermissions` | List permission grants on an item. | `{ value: [{ id, roles, grantedToV2, link }] }` | | `getPermission` | Get a single permission by `permId`. | A permission resource. | | `invite` | Grant access; `body` = `{ recipients, roles, requireSignIn, sendInvitation }`. | `{ value: [ permission ] }` | | `createLink` | Create a sharing link; `body` = `{ type, scope }`. | A permission with `{ link: { webUrl } }`. | | `deletePermission` | Remove a permission by `permId`. | Empty (HTTP 204). | ### Directory | Instruction | Description | Returns | | - | - | - | | `getUser` | Get a user by id or UPN/email. | A user resource `{ id, displayName, mail }`. | | `listUserMemberOf` | List groups/roles a user belongs to. | `{ value: [ group ] }` | | `checkUserMemberGroups` | Check which of given group ids a user is in; `body` = `{ groupIds: [] }`. | `{ value: [ ] }` | | `getGroup` | Get a group by id. | A group resource. | | `listGroupMembers` | List members of a group. | `{ value: [ user ] }` | ### Excel workbooks & Word documents (native content) Reading and writing file **content** natively is exposed on the **MCP surface** as the `workbook` and `documents` entity tools (see the *Agent builder* tab), not as separate Builder instructions, since they are routed internally. From an agent you call them by `action`: | Tool | Actions | Purpose | | - | - | - | | `workbook` (Excel `.xlsx`) | `listWorksheets`, `usedRange`, `getRange`, `listTables`, `listTableRows`, `updateRange`, `addTableRow`, `addWorksheet`, `createTable`, `executeFunction` | Read/write cell values natively via the Microsoft Graph Excel API: no download, no OCR. `addWorksheet`/`createTable` mutate the workbook; `executeFunction` evaluates an Excel function (`functionName` + named args) and returns `{ value }`. | | `documents` (Word `.docx`) | `getText`, `getStructure` | Read document content natively (OOXML parsed in-process). `getText` returns the full plain text (capped \~200 KB); `getStructure` returns the paragraph/table element tree plus metadata. | `Returns` shows the shape of the operation output (the underlying Microsoft Graph resource). To download a file, read the `@microsoft.graph.downloadUrl` returned by `getItem` / `listChildren` (a \~1h pre-signed link); content is not returned inline. ## DSUL Examples **Find a site and list its document libraries:** ```yaml theme={null} - Sharepoint.searchSites: search: 'Marketing' top: 5 output: sites - Sharepoint.listSiteDrives: siteId: '{{sites.value[0].id}}' output: drives ``` **List files at a drive root:** ```yaml theme={null} - Sharepoint.listRootChildren: driveId: '{{drives.value[0].id}}' top: 50 orderby: lastModifiedDateTime desc output: items ``` **Create a folder:** ```yaml theme={null} - Sharepoint.createFolder: driveId: '{{drives.value[0].id}}' parentItemId: root body: name: 'Reports 2026' folder: {} '@microsoft.graph.conflictBehavior': rename output: folder ``` **Run a Microsoft Search across document libraries:** ```yaml theme={null} - Sharepoint.searchQuery: body: requests: - entityTypes: - driveItem query: queryString: 'quarterly report' from: 0 size: 25 output: results ``` **Create a SharePoint list item:** ```yaml theme={null} - Sharepoint.createListItem: siteId: '{{sites.value[0].id}}' listId: '{{listId}}' body: fields: Title: 'New entry' Status: 'Open' output: created ``` ## Knowledge base **Goal:** index SharePoint documents into a knowledge base so an agent can search their **content**, and keep that base up to date. Before a base can be attached, a *Workspace builder* must have installed and configured the SharePoint app in a workspace and connected an account (see the *Workspace builder* tab). Nothing else is needed: the same app instance serves both the agent tools and the sync surface. The **Authorized agents** allowlist does **not** apply here — it gates the connector as an agent *tool*, and has no effect on synchronization. ## What can be synced **Document libraries** and the files inside them. SharePoint **pages and lists are not synced**: they are agent tools, not indexable resources. ## How it fits together ```mermaid theme={null} flowchart LR SP["SharePoint
Microsoft Graph"] Conn["SharePoint connector
MCP resources"] Sync["Knowledge Sync
browse · diff · index"] KB["Knowledge base
vector store"] Agent["Agent"] Sync -->|"resources/list · resources/read"| Conn Conn -->|"Graph API"| SP Sync -->|"documents"| KB Agent -->|"search"| KB Agent -.->|"per-reader access check"| Sync ``` The resource tree is three levels deep — a **site**, its **document libraries**, then any **item** inside them — and any container can be picked as a sync root: ```text theme={null} sharepoint://site/{siteId} sharepoint://site/{siteId}/drive/{driveId} sharepoint://site/{siteId}/drive/{driveId}/item/{itemId} ``` ## Attach the connector to a base Open the connector's **Configuration app** in the workspace where it is installed; it displays and copies that workspace's MCP endpoint: ```text theme={null} /workspaces//webhooks/.mcp ``` Go to **Knowledges → Connectors → New Connection → Your own MCP server**, paste the endpoint and click **Check**. Pick a site, then a document library, then descend into folders and confirm with **Use this location**. Everything below the selected root is synced, nested folders included. Choose an existing knowledge base or create one from the same step, then click **Sync Now**. Large libraries are spread over several runs; the schedule (*Hourly* to *Daily*, under **Auto-sync**) finishes the job. The full wizard, the run history and the connection settings are documented once for every provider in [Knowledges → Connectors](/products/ai-knowledge/connectors). This tab covers only what is specific to SharePoint. SharePoint is normally also published as a **catalog connector**, which appears under **Available Providers** and asks each person to sign in with their own Microsoft account. Attaching this connector's own endpoint instead is what lets a base be fed by an **application identity** (`clientCredentials` mode) rather than by a person — the credential then belongs to the workspace, and no reader ever signs in for the sync. ## Who may sync, and who may read | Moment | Acts as | Authorized by | | - | - | - | | Attaching the connection, browsing the tree | You | Your **role on the workspace** holding the connector's configuration — the right to read that workspace is the right to read this SharePoint through it | | A scheduled sync run | No user at all | The calling workspace must be listed in `knowledgeSync.trustedCallers`; the Knowledge Sync workspace ships there by default | | Answering a reader's question | The reader | A live per-reader access check (`items` / `checkAccess`) against Microsoft Graph | **Per-user access control is supported and worth keeping on.** The connector declares an access tool, so each reader's own rights are re-checked in SharePoint at query time: a file you lost access to stops appearing in answers without waiting for the next sync. Turning it off serves every synced document to anyone who can query the agent, whatever their SharePoint rights. Note that a connection backed by `clientCredentials` feeds the base with the **application's** reach — narrow it at the source (sites-selected permissions) rather than counting on the selection made in the wizard. ## What gets indexed | Aspect | Behavior | | - | - | | Document unit | One **driveItem** (a file) = one document. Sites, libraries and folders are containers, never indexed themselves. | | Content | Graph hands out a short-lived **pre-signed download URL**, so the bytes are fetched out of band — the format-aware path. Small text-like files (≤ 1 MB) are inlined directly instead, capped at 200 000 characters. | | Revision marker | `cTag`, falling back to `eTag`. Unchanged files are never re-read and never re-indexed. | | Identity | The **item id**. Renaming or moving a file inside the synced root therefore does *not* re-index it. | | Deletions | Each run is a **full traversal**: a file absent from a complete listing is removed from the base. A listing that failed halfway deletes nothing. | **The Knowledge profile this connector declares** — the descriptor Knowledges probes at `sharepoint://profile/knowledge`: | Field | Value | | - | - | | `provider` | `sharepoint-next` | | `hierarchy` | `site` › `drive` › `item` | | `canonical_uri` | `sharepoint://site/{siteId}/drive/{driveId}/item/{itemId}` | | `revision` | `cTag`, fallback `eTag` | | `read` | Pre-signed download URL for binaries; inline text ≤ 1 MB, 200 000 characters | | `list` | 50 resources per page by default, 200 max; `delta_on_drive: false` | | `access` | Tool `items`, action `checkAccess` | | `authentication` | `oauth`, `oauthCentral`, `clientCredentials`, `accessToken` | ## Troubleshooting the sync **The URL check says "You are not allowed to read it"**: you have no role on the workspace holding the connector's configuration. Ask its administrator for one — this is not about your SharePoint rights. **The URL check says "It answered, but could not serve its content"**: the connector itself is not fully configured. Open its configuration app and connect an account. **A site does not appear when browsing**: a site created moments ago is not searchable yet — `/sites?search=` is served by the SharePoint search index, which takes minutes to hours. It is reachable by path in the meantime. **A whole library syncs slowly**: that is expected — runs are bounded and the schedule finishes the job. Prefer selecting a folder, or several narrow connections, over one library-wide root. **A file is in the library but not in the base**: check its format is one the platform indexes, and that it is under the selected root. A file whose download failed is reported in the connection's synchronization errors rather than half-indexed. **A scheduled sync keeps running after a right was revoked**: the role check runs on the interactive paths only. A scheduled run is authorized as the platform's synchronization workspace — delete the connection to stop it for certain. *** ## Security The answers that hold for every connector (agent access, shared knowledge bases, credentials, models, egress) are on [Connector security](/apps-store/marketplace/connectors/security). This section lists what is specific to SharePoint. | Topic | SharePoint | | - | - | | Authentication family | Delegated OAuth (Microsoft Entra, authorization code with PKCE): each user connects their own Microsoft 365 account. An app-only mode (`clientCredentials`) also exists. | | Production modes | `oauthCentral` or `oauth` | | Modes to avoid in production | `accessToken` (testing only, and a Graph access token expires after about an hour). `clientCredentials` acts as the application, not as the user: avoid it when per-user permissions are required. | | Read-only scopes | `offline_access`, `User.Read`, `Sites.Read.All`, `Files.Read.All` (the **Read-only preset** of the configuration app). These are the default with your own Microsoft Entra app; the platform's central client requests `Sites.ReadWrite.All` and `Files.ReadWrite.All` by default. | | Agent allowlist | Yes, on the tenant endpoint (empty at installation). The global endpoint accepts every agent. | | Per-reader access control on knowledge bases | Yes: each file is checked against the reader's own Microsoft 365 connection, even when the base is synchronized in `clientCredentials` mode. | | Outbound hosts | `graph.microsoft.com`, `login.microsoftonline.com`, and your tenant's SharePoint hosts (for example `contoso.sharepoint.com`, and `contoso-my.sharepoint.com` for OneDrive files): when a user approves an attachment, the platform fetches the file server-side from its pre-signed download link. | | Audit events | None specific to this connector | With the read-only scopes, Microsoft refuses every folder creation, rename, move, copy, delete, sharing link, list item change and Excel cell write. `Sites.Read.All` and `Files.Read.All` still reach every site and file the user can open: the configuration app offers no scope that limits the connector to chosen sites. In `clientCredentials` mode, the application permissions apply to every site of the tenant, whoever calls the agent. *** ## Error Handling | HTTP code | Meaning | | - | - | | `400` | Bad request: invalid parameters or malformed body (e.g. bad OData filter, invalid driveItem/list resource). | | `401` | Unauthorized: the Microsoft Graph access token is missing, expired or revoked. The user must reconnect (OAuth modes). | | `403` | Forbidden: insufficient Graph scope/permission, missing admin consent (application mode), or the account lacks access to the site/drive/item. | | `404` | Not found: the site, drive, item, list or permission id does not exist or is not visible to the account. | | `429` | Throttled: Microsoft Graph rate limit; back off and retry (honor `Retry-After`). | | `500` / `503` | Microsoft Graph service error: transient; retry shortly, no reconnection needed. | ### Common Issues **"This agent is not authorized to use this connector"**: The calling agent is not in the allowlist. Open the configuration app → **Authorized agents** → tick this agent (or enable **Allow all agents**) and Save. **"The calling agent could not be identified"**: The MCP capability *Scope* does not declare `agent_id`, so Agent Creator never injects the agent identity. Set the Scope to `context_id,agent_id,user_id` on the capability, then allow the agent in the config app. **"Microsoft Graph is not connected for this user"**: No per-user OAuth token. Open the configuration app (OAuth mode) and click **Connect**, or use the agent's connect flow. **"Microsoft Graph token refresh failed … must reconnect"**: The stored refresh token was revoked or expired (Microsoft Entra invalidated it, or it aged past its limit). The connection is dropped automatically; the user must reconnect from the config app. **"Microsoft Graph not authenticated" / "OAuth is not configured"**: Neither a tenant OAuth client nor the central platform client is available. Set the client ID/secret/tenant in the config app, or ask the platform maintainer to provision the central Entra OAuth client. **`client_credentials` exchange failed**: In application mode, check the Application (client) ID / secret, the tenant id, and that a Global Administrator granted **admin consent** for the application Graph permissions. **"Site not found"**: The site id format is `hostname,siteCollectionId,siteId`. Use `sites` `search` (or Graph Explorer) to find the correct id. **Microsoft Entra redirect URI rejected**: Entra rejects a colon in the redirect URI path. Register the redirect URI with the workspace's **raw id** (`/workspaces//webhooks/oauthCallback`), not the `slug:` form; copy the exact value from the config app. ## External Resources Official reference for the SharePoint sites, drives, files, lists and permissions REST APIs. Learn how Agent Creator agents consume MCP tools in Prisme.ai. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.