Word - Prisme.ai

The Word connector provides Microsoft Word document operations through the Microsoft Graph API. It can be used as a Builder app for deterministic document workflows or as an MCP server for AI agents that need to create, inspect, convert, update, version, and manage .docx files stored in OneDrive or SharePoint.

Document Operations

Read metadata, download content, upload DOCX bytes, convert files, and delete documents

Structured Authoring

Build valid Word documents from a JSON specification with headings, paragraphs, tables, lists, images, and formatting

Governance & Lifecycle

Search files, inspect document structure, manage versions, checkout locks, following, and analytics

Prerequisites

A Microsoft Entra ID / Azure AD application registered in your tenant
A client secret for that application
Microsoft Graph permissions granted with admin consent:
- Files.Read.All for read-only document access
- Files.ReadWrite.All for upload, update, delete, checkout, check-in, restore, and follow operations
- Sites.Read.All or Sites.ReadWrite.All when accessing SharePoint-hosted documents
Your Directory (tenant) ID and Application (client) ID
Optional SharePoint Site ID when the default target is a SharePoint site instead of the user’s OneDrive

Usage as App
Usage as MCP

Usage as App

Installation

Go to Apps in your workspace
Search for Word and install it
Open the app instance configuration and fill in the required Microsoft Graph credentials

Configuration

Field	Description
Azure Client ID	Microsoft Entra application (client) ID used to call Microsoft Graph
Azure Client Secret	Microsoft Entra application client secret, stored as a workspace secret
Azure Tenant ID	Microsoft Entra directory (tenant) ID
SharePoint Site ID	Optional default SharePoint site ID for SharePoint-based document operations

File Access

Word operations target Microsoft Graph drive items. For OneDrive files, pass an itemId or path and optionally a driveId. For SharePoint files, also pass siteId or configure a default SharePoint Site ID on the app instance.

- Word.getDocument:
    itemId: '{{documentItemId}}'
    driveId: '{{driveId}}'
    output: document

- Word.getDocumentByPath:
    path: Documents/Quarterly Report.docx
    siteId: '{{sharePointSiteId}}'
    driveId: '{{driveId}}'
    output: document

Available Instructions

Every instruction resolves Microsoft Graph credentials through the workspace configuration. Most operations accept driveId and siteId to override the configured default target.

Document Lookup & Search

Instruction	Arguments
`getDocument`	`itemId`*, `select`, `expand`, `driveId`, `siteId`
`getDocumentByPath`	`path`*, `select`, `expand`, `driveId`, `siteId`
`searchDocuments`	`query`*, `top`, `driveId`, `siteId`
`getDocumentStructure`	`itemId`*, `includeContent`, `maxContentLength`, `driveId`, `siteId`

Content Transfer & Creation

Instruction	Arguments
`downloadDocument`	`itemId`*, `driveId`, `siteId`
`downloadDocumentByPath`	`path`*, `driveId`, `siteId`
`uploadDocument`	`itemId`, `content`, `contentType`, `driveId`, `siteId`
`uploadDocumentByPath`	`path`, `content`, `contentType`, `driveId`, `siteId`
`buildDocument`	`itemId` or `path`, `spec`*, `driveId`, `siteId`
`convertDocument`	`itemId`, `format`, `driveId`, `siteId`

Metadata & Lifecycle

Instruction	Arguments
`updateDocument`	`itemId`*, `name`, `description`, `driveId`, `siteId`
`deleteDocument`	`itemId`*, `driveId`, `siteId`

Versions

Instruction	Arguments
`listVersions`	`itemId`*, `driveId`, `siteId`
`getVersion`	`itemId`, `versionId`, `driveId`, `siteId`
`downloadVersionContent`	`itemId`, `versionId`, `driveId`, `siteId`
`restoreVersion`	`itemId`, `versionId`, `driveId`, `siteId`

Checkout

Instruction	Arguments
`checkoutDocument`	`itemId`*, `driveId`, `siteId`
`checkinDocument`	`itemId`*, `comment`, `driveId`, `siteId`
`discardCheckout`	`itemId`*, `driveId`, `siteId`

Collaboration & Analytics

Instruction	Arguments
`followDocument`	`itemId`*, `driveId`, `siteId`
`unfollowDocument`	`itemId`*, `driveId`, `siteId`
`getAnalytics`	`itemId`*, `driveId`, `siteId`

Arguments flagged with * are required. buildDocument requires spec and either itemId for rewrite mode or path for create mode.

DSUL Examples

Search for Word Documents

- Word.searchDocuments:
    query: contract
    top: 10
    driveId: '{{driveId}}'
    output: documents

Build a New Word Document

- Word.buildDocument:
    path: Reports/generated-summary.docx
    driveId: '{{driveId}}'
    spec:
      properties:
        title: Generated Summary
        author: Prisme.ai
      sections:
        - content:
            - type: heading
              level: 1
              text: Quarterly Summary
            - type: paragraph
              text: This document was generated from a Prisme.ai workflow.
            - type: table
              headers:
                - Metric
                - Value
              rows:
                - - Revenue
                  - '{{revenue}}'
                - - Active customers
                  - '{{customerCount}}'
    output: builtDocument

Inspect and Convert a Document

- Word.getDocumentStructure:
    itemId: '{{documentItemId}}'
    includeContent: true
    output: structure
- Word.convertDocument:
    itemId: '{{documentItemId}}'
    format: pdf
    output: pdfContent

Restore a Previous Version

- Word.listVersions:
    itemId: '{{documentItemId}}'
    output: versions
- Word.restoreVersion:
    itemId: '{{documentItemId}}'
    versionId: '{{versions.value[0].id}}'
    output: restored

Usage as MCP

The Word MCP workspace exposes the same document operations as JSON-RPC tools. The MCP endpoint receives the mcp-api-key header, routes tools/call requests through routeToolCall, and delegates each operation to the Word app workspace, where Microsoft Graph authentication and Graph URL construction are handled.

MCP Configuration

Field	Description
MCP API Key	Configured on the Word MCP workspace and sent through the `mcp-api-key` header for MCP endpoint calls

Plug into an Agent Creator capability

Agents consume MCP servers directly through Agent Creator capabilities. This is the preferred way to expose Word tools to an agent.

Create or open a workspace

From the Prisme.ai console, create a new workspace or open the workspace that will host the connector.

Install and configure the Word app

Install Word and configure the Microsoft Graph credentials from the Usage as App tab.

Copy the MCP endpoint and API key

Open the Word MCP app instance configuration and copy the MCP Endpoint and MCP API Key values.

Open Agent Creator

Open the agent you want to extend and add a capability.

Add the MCP capability

Select a dedicated Word capability if one exists. Otherwise, use the generic custom_mcp capability, paste the MCP endpoint as the server URL, then add this header:

{
  "mcp-api-key": "your-mcp-api-key"
}

Brief the agent

Tell the agent when to use Word tools, which document locations it may access, and when to ask for confirmation before destructive actions such as deleting files, overwriting content, restoring versions, or discarding checkout changes.

Legacy MCP Install (Advanced > Tools)

Use this flow to plug the Word MCP into an AI Knowledge agent that does not yet support the native Agent Creator capability picker.

Install the Word app

Install and configure the Word app in the same workspace as your agent.

Copy the MCP credentials

Open the MCP app instance configuration and copy the MCP Endpoint and MCP API Key.

Open your AI Knowledge project

Navigate to Advanced > Tools.

Add an MCP tool

Click Add, select the MCP tab, and paste the MCP endpoint URL.

Add the auth header

Add the signed API key in the headers field:

{
  "mcp-api-key": "your-mcp-api-key"
}

Save

The agent can now list and call the Word MCP tools.

Output Formats

Every tool accepts an outputFormat parameter that controls the MCP response shape:

verbose (default) - human-readable text for LLM consumption
structured - machine-readable JSON returned as text and in structuredContent
both - currently returns JSON text and structuredContent, matching structured output

Available Tools

Document Lookup & Search

Tool	Description
`getDocument`	Get Word document metadata by ID
`getDocumentByPath`	Get Word document metadata by path
`searchDocuments`	Search for Word documents in a drive
`getDocumentStructure`	Parse Word document and return element tree

Content Transfer & Creation

Tool	Description
`downloadDocument`	Download Word document content by ID
`downloadDocumentByPath`	Download Word document content by path
`uploadDocument`	Upload or replace a Word document from base64-encoded DOCX bytes, up to 4 MB
`uploadDocumentByPath`	Upload a Word document to a path from base64-encoded DOCX bytes
`buildDocument`	Create a valid Word `.docx` from a JSON spec and upload it
`convertDocument`	Convert a Word document to PDF or HTML format

Metadata & Lifecycle

Tool	Description
`updateDocument`	Update document metadata such as name or description
`deleteDocument`	Delete a document by moving it to the recycle bin

Versions

Tool	Description
`listVersions`	List all versions of a Word document
`getVersion`	Get metadata for a specific document version
`downloadVersionContent`	Download content of a specific document version
`restoreVersion`	Restore a document to a previous version

Checkout

Tool	Description
`checkoutDocument`	Check out a document to lock it for exclusive editing
`checkinDocument`	Check in a document to release the lock and save changes
`discardCheckout`	Discard checkout and revert to the last checked-in version

Collaboration & Analytics

Tool	Description
`followDocument`	Follow a document to receive notifications
`unfollowDocument`	Stop following a document
`getAnalytics`	Get document analytics such as views and viewers when available from Microsoft Graph

Tool Details

`buildDocument`

Creates or rewrites a Word document from a JSON document specification.

{
  "name": "buildDocument",
  "arguments": {
    "path": "Reports/generated-summary.docx",
    "driveId": "b!drive-id",
    "spec": {
      "properties": {
        "title": "Generated Summary",
        "author": "Prisme.ai"
      },
      "sections": [
        {
          "content": [
            { "type": "heading", "level": 1, "text": "Quarterly Summary" },
            { "type": "paragraph", "text": "Generated by an AI agent." },
            {
              "type": "table",
              "headers": ["Metric", "Value"],
              "rows": [["Revenue", "$120k"], ["Customers", "42"]]
            }
          ]
        }
      ]
    },
    "outputFormat": "structured"
  }
}

Parameter	Required	Description
`spec`	Yes	JSON specification with `sections` and document content elements
`itemId`	No	Existing document item ID for rewrite mode
`path`	No	File path for create mode; required when `itemId` is omitted
`driveId`	No	Drive ID; defaults to the configured OneDrive or SharePoint drive context
`siteId`	No	SharePoint site ID override

`getDocumentStructure`

Downloads a DOCX file and parses it into a structured element tree that agents can inspect before rewriting or summarizing content.

{
  "name": "getDocumentStructure",
  "arguments": {
    "itemId": "01ABCDEF2345",
    "includeContent": true,
    "maxContentLength": 2000,
    "outputFormat": "structured"
  }
}

Parameter	Required	Description
`itemId`	Yes	Document drive item ID
`includeContent`	No	Include text content in parsed elements
`maxContentLength`	No	Maximum content length returned per element
`driveId`	No	Drive ID override
`siteId`	No	SharePoint site ID override

`uploadDocumentByPath`

Uploads a base64-encoded DOCX file to a drive path.

{
  "name": "uploadDocumentByPath",
  "arguments": {
    "path": "Templates/template.docx",
    "content": "UEsDBBQAAAA...",
    "contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
  }
}

Parameter	Required	Description
`path`	Yes	Target path in the drive
`content`	Yes	Base64-encoded DOCX bytes, up to 4 MB
`contentType`	No	MIME type; defaults to Word `.docx`
`driveId`	No	Drive ID override
`siteId`	No	SharePoint site ID override

`searchDocuments`

Searches for Word documents in the configured drive context.

{
  "name": "searchDocuments",
  "arguments": {
    "query": "contract",
    "top": 10,
    "outputFormat": "both"
  }
}

Parameter	Required	Description
`query`	Yes	Search query text
`top`	No	Maximum number of results to return
`driveId`	No	Drive ID override
`siteId`	No	SharePoint site ID override

`convertDocument`

Converts a Word document to another format supported by Microsoft Graph download conversion.

{
  "name": "convertDocument",
  "arguments": {
    "itemId": "01ABCDEF2345",
    "format": "pdf",
    "outputFormat": "structured"
  }
}

Parameter	Required	Description
`itemId`	Yes	Document drive item ID
`format`	Yes	Target format, typically `pdf` or `html`
`driveId`	No	Drive ID override
`siteId`	No	SharePoint site ID override

`restoreVersion`

Restores a document to a previous version.

{
  "name": "restoreVersion",
  "arguments": {
    "itemId": "01ABCDEF2345",
    "versionId": "2.0",
    "outputFormat": "verbose"
  }
}

Parameter	Required	Description
`itemId`	Yes	Document drive item ID
`versionId`	Yes	Version ID returned by `listVersions`
`driveId`	No	Drive ID override
`siteId`	No	SharePoint site ID override

Error Handling

HTTP Status	Error	Solution
`400`	Invalid request, path, format, or document spec	Check required arguments, Graph path syntax, and `spec.sections` for `buildDocument`
`401`	Authentication failed	Verify Azure Client ID, Client Secret, Tenant ID, and token permissions
`403`	Insufficient Microsoft Graph permissions	Grant admin consent for the required Files and Sites permissions
`404`	Document, drive, site, or version not found	Verify `itemId`, `path`, `driveId`, `siteId`, and `versionId`
`409`	Conflict or checkout state prevents the operation	Check the document checkout status or retry after releasing the lock
`413`	Generated or uploaded content is too large	Keep base64 DOCX uploads under the 4 MB connector limit
`429`	Microsoft Graph throttling	Retry later or reduce request volume
`500`	Microsoft Graph or connector runtime error	Inspect the tool response and workspace execution logs

Common Issues

“Authentication failed” - The Microsoft Graph credentials are missing, expired, or lack admin consent. Confirm the configured Azure app can acquire a token for Microsoft Graph. “Either itemId or path must be provided” - buildDocument supports rewrite mode with itemId or create mode with path. Provide one of them with a valid spec. Upload exceeds 4 MB - uploadDocument, uploadDocumentByPath, and generated buildDocument uploads use the small-file Microsoft Graph upload path. Reduce the document size before retrying. SharePoint document not found - SharePoint operations usually need the correct siteId and driveId. Configure a default SharePoint Site ID or pass these arguments per call.

External Resources

Microsoft Graph DriveItem API

Reference for OneDrive and SharePoint file metadata, content, versions, and lifecycle operations.

Tool Agents

Learn how to expose connector tools to AI agents through Prisme.ai capabilities.

Document Operations

Structured Authoring

Governance & Lifecycle

​Prerequisites

​Usage as App

​Installation

​Configuration

​File Access

​Available Instructions

​Document Lookup & Search

​Content Transfer & Creation

​Metadata & Lifecycle

​Versions

​Checkout

​Collaboration & Analytics

​DSUL Examples

​Search for Word Documents

​Build a New Word Document

​Inspect and Convert a Document

​Restore a Previous Version

​Usage as MCP

​MCP Configuration

​Plug into an Agent Creator capability

​Legacy MCP Install (Advanced > Tools)

​Output Formats

​Available Tools

​Document Lookup & Search

​Content Transfer & Creation

​Metadata & Lifecycle

​Versions

​Checkout

​Collaboration & Analytics

​Tool Details

​buildDocument

​getDocumentStructure

​uploadDocumentByPath

​searchDocuments

​convertDocument

​restoreVersion

​Error Handling

​Common Issues

​External Resources

Microsoft Graph DriveItem API

Tool Agents

Prerequisites

Usage as App

Installation

Configuration

File Access

Available Instructions

Document Lookup & Search

Content Transfer & Creation

Metadata & Lifecycle

Versions

Checkout

Collaboration & Analytics

DSUL Examples

Search for Word Documents

Build a New Word Document

Inspect and Convert a Document

Restore a Previous Version

Usage as MCP

MCP Configuration

Plug into an Agent Creator capability

Legacy MCP Install (Advanced > Tools)

Output Formats

Available Tools

Document Lookup & Search

Content Transfer & Creation

Metadata & Lifecycle

Versions

Checkout

Collaboration & Analytics

Tool Details

`buildDocument`

`getDocumentStructure`

`uploadDocumentByPath`

`searchDocuments`

`convertDocument`

`restoreVersion`

Error Handling

Common Issues

External Resources