Build an AI Word add-in with Office.js and Vespper

Our open-source Word add-in gives you a starting point for building an AI assistant inside Microsoft Word. It uses Office.js and React for the task pane, Mastra to run the agent, and Vespper DOCX MCP to read, search, and edit the open document.

In this tutorial, you'll run the example locally, make your first tracked edit, and see which parts to change when building your own add-in. The example code is MIT-licensed. Running it requires a Vespper API key and a model-provider API key.

What you'll build

The add-in opens a chat pane alongside your Word document. A user asks for a change, the agent edits the document, and revisions stream back into Word while the agent is working.

The example includes:

• Streamed document edits, so users can see changes as they arrive.
• Tracked changes that follow Word's current Track Changes setting.
• Selected-text and pasted-image context to give the agent more information about the request.
• Model selection and an editable tracked-change author in the task pane.

Watch: The Vespper Word add-in streaming edits into an open document

How Office.js and Vespper fit together

Office.js connects the add-in to the open Word document. The local server runs the agent, and Vespper handles document editing through tools including read_document, search_document, and edit_document.

Part	Responsibility in this example
Office.js and React	Show the task pane, read the open DOCX and its tracking mode, and apply returned revisions in Word.
Local Node.js server and Mastra	Receive the document and user request, run the agent, and stream updates to the task pane.
Vespper TypeScript SDK and DOCX MCP	Manage the document session and give the agent tools to read, search, and edit the document.

The server opens a Vespper session for each agent turn. The document is uploaded once for that session, and subsequent tool calls use the session ID. The agent works with HTML through the document tools; Vespper returns updated DOCX revisions.

The API keys stay in the local server's environment and are not bundled into the task pane. The workflow still calls Vespper and your selected model provider.

Run the Word add-in locally

You'll need Microsoft Word desktop on macOS or Windows, Node.js 22.13 or newer, Git, a Vespper account, and an API key for OpenAI, Anthropic, or Google. These steps use the example's default OpenAI configuration.

1. Clone and install the example

git clone https://github.com/vespperhq/examples.git
cd examples/word-add-in
npm install

This installs the task pane, local server, agent dependencies, and Office add-in development tools.

2. Configure your API keys

Create a key on the Vespper API keys page. Copy the secret when it is shown, then create your local environment file.

On macOS:

cp .env.example .env

On Windows PowerShell:

Copy-Item .env.example .env

Open .env and replace the placeholders:

VESPPER_API_KEY=sk_live_your_key_here
VESPPER_MCP_URL=https://mcp.vespper.com/mcp
OPENAI_API_KEY=sk-your_openai_key_here

The repository ignores .env in Git. Keep your keys in that file rather than putting them in the React code.

To use another model provider, configure its key and set WORD_AGENT_MODEL to the corresponding model. For example, the sample supports:

ANTHROPIC_API_KEY=sk-ant-your_anthropic_key_here
WORD_AGENT_MODEL=anthropic/claude-sonnet-4.5

Only the selected model provider's key is needed. The README lists the supported environment variables, including those for Google models.

3. Set up local HTTPS

The add-in loads its task pane over HTTPS. Install the development certificate using the repository's setup command:

npm run setup:certs

Follow the certificate installation prompts. You can check the certificate setup with npm run setup:certs:check.

4. Launch the add-in in Word

npm start

This builds the task pane, starts the local HTTPS server at https://localhost:3100, launches Word, and sideloads the add-in. If the pane doesn't open automatically, choose Home → Add-ins → Vespper.

Open the local health endpoint. Both vespperConfigured and agentConfigured should be true. These flags indicate that keys are present for Vespper and the configured default model; the first successful edit verifies that the integration works with those credentials.

Make your first tracked edit

Start with a simple document so you can see exactly what changed:

1. Create and save a Word document containing: The draft is due on Friday.
2. Turn on Review → Track Changes.
3. Open the Vespper task pane and ask: Change the deadline from Friday to Monday.
4. Review the edit in Word, then accept or reject it.

The sample reads Word's tracking mode when you submit the request. With tracking enabled, the edit should appear as a deletion and an insertion. With tracking disabled, changes are applied directly. You can set the tracked-change author in the add-in's settings.

For a more specific request, select text in Word before submitting your prompt. You can also paste an image into the prompt to give the agent visual context.

How streamed edits reach Word

The integration lives in api/agent.ts. It opens a document session and patches the MCP tools with the session ID, author, and tracking preference. This excerpt shows how the SDK also forwards document updates to the task pane:

await client.patchMCPTools({
  mcp,
  sessionId,
  author: opts.author,
  trackChanges: opts.trackChanges,
  onDocumentUpdated(update) {
    output.write({
      type: "edit_applied",
      docx_b64: Buffer.from(update.document).toString("base64"),
      edit_count: update.editCount,
      revision: update.revision,
    });
  },
});

The example wraps edit_document to parse edit arguments as the model produces them. Each completed edit pair can be sent to Vespper before the model finishes generating the full tool input. The wrapper supplies the streaming batch ID and edit index, while the SDK supplies the ordinary session metadata and retains updated document revisions.

The task pane receives those revisions and applies them through Office.js. At the end of the turn, the server disconnects the MCP client and closes the Vespper session. The Word add-in cookbook documents the complete integration.

Handle concurrent typing, revision order, and cancellation

Changing a file on disk does not synchronize Word's active document. A developer question about live Word editing asks for this distinction explicitly. Office.js supplies the editor integration here; Vespper's tools are editor-agnostic, and another editor needs its own adapter for returned DOCX updates.

Track three separate states in that adapter: the model proposing an edit, the service applying it, and the editor displaying the returned revision. Parse complete edit pairs before submitting them; a partial JSON fragment is not a document mutation.

Each agent turn starts from a document snapshot. If the user types afterward, applying an output derived from the older snapshot can overwrite newer work. Track the input version, serialize conflicting operations, and choose a conflict policy before supporting simultaneous user and agent edits. Prevent a late update from replacing a newer displayed revision. These are requirements for your application, not a claim that the sample implements collaborative merging.

On cancellation, stop scheduling edits and retain the latest successful state before closing the session. Tell the user whether changes were already applied. Test cancellation after one successful edit, a failed update, typing during an operation, and both Word tracking modes. Compare the final saved document with the last displayed revision.

Customize the add-in for your workflow

Once the sample runs, these are the main places to start:

File	What to change
api/agent.ts	The agent's instructions and editing workflow.
add-in/src/	The React task pane, chat interface, and settings.
add-in/src/office/document.ts	Reading the open document, checking tracking mode, and applying DOCX revisions through Office.js.
add-in/manifest.xml	The add-in's display name, ribbon button, and task-pane location.

For example, you could adapt the agent's instructions to revise reports against a house style, or use selected-text context to focus requests on a particular passage. Keep the three document tools connected as you build out the workflow.

Use npm run dev to build and serve the add-in without launching Word, and npm run typecheck to check your TypeScript changes. When you're finished with the local example, run npm stop to stop and unregister the development add-in.

This tutorial runs the sample locally. Distributing an add-in to other users requires replacing the localhost configuration and choosing how to host and deploy it.

Start with the complete Word add-in example on GitHub. For the same document-editing tools in an agent outside Word, follow the Vespper quickstart.