API reference

vespper-docx-mcp is the hosted gateway for reading and editing Word documents. It authenticates requests, meters usage, and exposes three tools that operate on the current document in a short-lived session.

Server


MCP endpoint	`https://mcp.vespper.com/mcp`
Session endpoint	`https://mcp.vespper.com/v1/docx/sessions`
Transport	Streamable HTTP
Auth	`Authorization: Bearer sk_live_...`
Health	`GET https://mcp.vespper.com/health`

Clients discover the tools and their schemas with tools/list.

Tools

Read document

Return a range of pages as HTML.

Search document

Regex-match blocks without loading the whole document.

Edit document

Apply old → new edits to the document.

Tool	Arguments	Returns
`read_document`	`start_page`, `end_page`	HTML, paging state, token counts, bytes, and revision
`search_document`	`pattern`, `start_at`	Matching blocks, match counts, paging state, and revision
`edit_document`	`edits`	Latest DOCX, applied and failed edit counts, revision, message, and cost

Pass the descriptions returned by tools/list through to your model. They carry the rules for complete-block anchors, lazy classes, disambiguation, batching, partial-batch recovery, and tracked changes.

Document sessions

Upload the .docx once before starting the agent loop. Use the Vespper SDK in Python or TypeScript; use the HTTP endpoint directly when integrating without an SDK:

curl --request POST \
  --url https://mcp.vespper.com/v1/docx/sessions \
  --header "Authorization: Bearer $VESPPER_API_KEY" \
  --header "Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document" \
  --data-binary @sample.docx

from dotenv import load_dotenv
from vespper import Vespper

load_dotenv()

client = Vespper()
session_id = await client.open_session("./sample.docx")

import "dotenv/config";
import Vespper from "vespper";

const client = new Vespper();
const sessionId = await client.openSession("./sample.docx");

The underlying request returns HTTP 201:

{
  "session_id": "0199f1d4-5e57-7000-8000-123456789abc",
  "current_revision": 0
}

open_session() and openSession() return the session_id string. Your client then attaches the session ID to each tool call through MCP _meta. The model sees only the clean tool arguments:

`_meta` key	Required	Description
`com.vespper/session-id`	Yes	The document session returned by `POST /v1/docx/sessions`
`com.vespper/author`	No	Name Word shows on tracked edits. Defaults to `Vespper`
`com.vespper/track-changes`	No	Whether new edits are tracked. Defaults to `true`

A raw tool call looks like this:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_document",
    "arguments": { "pattern": "(?i)effective date" },
    "_meta": {
      "com.vespper/session-id": "0199f1d4-5e57-7000-8000-123456789abc"
    }
  }
}

Use Vespper SDK auto-patching when it supports your MCP client. It injects _meta and retains the latest DOCX automatically. With manual wiring, add _meta per call or at the transport boundary. The Quickstart shows both approaches.

Control tracked changes behavior

By default, edit_document records new edits as Word tracked changes. Configure the author and tracking behavior when you patch the MCP client, or pass the same settings manually through _meta:

Vespper SDK
Raw MCP metadata

await client.patchMCPTools({
  mcp,
  sessionId,
  author: "Vespper Agent",
  trackChanges: false,
});

await client.patch_mcp_tools(
    mcp=mcp,
    session_id=session_id,
    author="Vespper Agent",
    track_changes=False,
)

{
  "_meta": {
    "com.vespper/session-id": "0199f1d4-5e57-7000-8000-123456789abc",
    "com.vespper/author": "Vespper Agent",
    "com.vespper/track-changes": false
  }
}

This setting controls only the new edits made by that call. Existing tracked changes remain unchanged unless an edit explicitly accepts, rejects, or modifies them. Read, search, and edit responses include current_revision, the revision of the session document used or produced by that call. Each successful edit updates the session’s canonical document and increments its revision. When the agent finishes or is cancelled, close the session:

curl --request DELETE \
  --url https://mcp.vespper.com/v1/docx/sessions/0199f1d4-5e57-7000-8000-123456789abc \
  --header "Authorization: Bearer $VESPPER_API_KEY"

await client.close_session(session_id)
await client.close()

await client.closeSession(sessionId);

A successful close returns HTTP 204.

The session belongs to the user who created it. Missing, closed, or user-mismatched sessions are rejected. Always close sessions in a finally block; abandoned sessions are cleaned up automatically, but explicit cleanup releases their document state immediately.

Choosing a primitive

Reading the whole document is rarely the right first move.

You know	Start with
The text to change (a name, a date, a clause)	`search_document` - it returns each hit as a complete, pasteable block
Nothing about the document’s shape	`read_document` - page through as far as the task needs
The document is short	`read_document` once

Both tools return the same HTML, so an anchor copied from either is equally valid in edit_document.

Typical flow

open session → patch or wire tools → search or read → edit → save DOCX → close session

The server owns the current document for the session. Tool calls carry only the session ID, so clients do not resend DOCX bytes or thread returned base64 into the next call. edit_document still returns the latest cumulative DOCX for saving, downloading, or live display.

Authentication

Send Authorization: Bearer sk_live_... on the MCP connection and session HTTP requests. API keys are never tool parameters. Create a key on the API keys page.

Verify a connection

Call tools/list with your key and confirm that it returns read_document, search_document, and edit_document. Then open a document session, call search_document with its session ID, and close the session. This verifies authentication, document upload, conversion, and cleanup.

Overview

Primitives

Server

Tools

Read document

Search document

Edit document

Document sessions

Control tracked changes behavior

Choosing a primitive

Typical flow

Authentication

Verify a connection

​Server

​Tools

Read document

Search document

Edit document

​Document sessions

​Control tracked changes behavior

​Choosing a primitive

​Typical flow

​Authentication

​Verify a connection

Server

Tools

Document sessions

Control tracked changes behavior

Choosing a primitive

Typical flow

Authentication

Verify a connection