Skip to main content
Vespper exposes three primitives over MCP. They are stateless data operations designed to be chained inside an agent loop: every call carries the document, and edit_document hands back the patched bytes for the next call.

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 as Word tracked changes.

​
Attaching the document

The document is never a tool argument. Your client attaches it to the per-call MCP _meta object, base64-encoded, under reverse-DNS namespaced keys: That keeps the tool schemas clean — read_document(), search_document(pattern), edit_document(edits) — so the model chooses the edit and never spends context on base64.
Because the client injects _meta, a stock MCP client that cannot set it cannot drive these tools; calls come back with No document attached. See the Quickstart for the framework and native paths that inject it for you.

​
Choosing a primitive

Reading the whole document is rarely the right first move. Both tools return the same HTML, so an anchor copied from either is equally valid in edit_document.

​
Typical flow

There is no server-side document session. Pass the current bytes on every call, and after edit_document continue with the base64 it returns or decode it to save a .docx.

​
Billing

read_document and search_document are metered as reads; edit_document is metered as an edit. Every response carries the cost_usd for that call.