Available MCP Tools

When you connect to the SuperDocs MCP server, these 38 tools become available to your AI tool. Each tool is designed to surface SuperDocs’ real capabilities — structural editing of styled documents, multi-document sessions, durable Files that persist across sessions, optional cross-session memory and search, fidelity-preserving export, multimodal vision, human-in-the-loop approval, and large-file upload/download without bloating agent context.

Chat

Tool	Description	Key parameters
`chat`	Edit, draft, or restructure a document using natural language. Preserves tables, styling, and formatting. Returns AI response and structural changes. Sessions can hold multiple open documents — pass `document_id` to target a specific one (omit it to work on the focused document), or just name the document in your message; the AI can also open a brand-new document on request (“put this summary in a new document”), or duplicate an existing document and change only its values while keeping the original layout and formatting exactly (“recreate this invoice for a new client with these amounts”). For large documents (>20 pages), set `response_mode='compact'` to skip the full HTML in the response and get only per-section diffs (`chunk_diffs`) instead — saves thousands of tokens per turn. To read sections, just ask in natural language (“show me the force majeure section”) and the AI returns the content in the reply. Optional cross-session context (all OFF by default, owner-scoped): set `cross_session_memory=true` to let the AI carry durable preferences from this API key’s prior sessions, and `cross_session_search=true` to let it search your own earlier documents and chats.	`message`, `session_id`, `document_html`, `document_id`, `model_tier`, `thinking_depth`, `approval_mode`, `response_mode`, `image_attachments`, `cross_session_memory`, `cross_session_search`, `cross_session_memory_key`, `cross_session_scope`
`chat_async`	Start a long-running or HITL-approved AI edit; returns a job_id to poll. Use for multi-step edits or `approval_mode='ask_every_time'`. Accepts the same `document_id` targeting and the same optional `cross_session_` context fields as `chat`. For large documents, set `response_mode='compact'`* so polled job results skip the full HTML and surface only per-section diffs. A long edit may pause partway through and ask to continue — resume it with `continue_chat` (see below), not `approve_change`.	`message`, `session_id`, `document_html`, `document_id`, `model_tier`, `thinking_depth`, `approval_mode`, `response_mode`, `cross_session_memory`, `cross_session_search`, `cross_session_memory_key`, `cross_session_scope`
`approve_change`	Approve or deny AI-proposed document changes one-by-one or in batch (HITL workflow). Supports per-change feedback for the AI to revise on.	`session_id`, `job_id`, `change_id`, `approved`, `feedback`, `changes`
`continue_chat`	Resume a large edit that paused partway through and asked whether to keep going. When a job is awaiting approval and the pause is a continue prompt (a `continue_prompt` streaming event was sent), call this with `continue=true` to finish the remaining work, or `continue=false` to stop and keep what’s already applied. Use this — not `approve_change` — for this kind of pause.	`job_id`, `continue`

Cross-session context is opt-in and owner-scoped. cross_session_memory and cross_session_search default to off — turn them on per request. Everything stays scoped to the API key that owns it; the AI never reaches into another account’s sessions. For B2B2C integrators serving many end-customers under one key, pass cross_session_memory_key (a stable per-end-customer key, so each customer gets their own durable memory note) and/or cross_session_scope (a list of session ids to narrow cross-session search to that customer’s work). Wipe the memory note any time with clear_cross_session_memory — note its parameter is named memory_key (you pass the same value you sent as cross_session_memory_key on chat).

Documents

Tool	Description	Key parameters
`upload_document_base64`	Upload `.docx` / PDF / HTML / MD / RTF as the active editable document with chunk-ID structural editing. Tables, borders, shading, and styling preserved on edit and export. Also works for AI-generated outlines. For files >100KB, prefer the `request_upload_url` flow below — base64 through the agent’s context is slow and token-expensive at scale.	`filename`, `file_base64`, `session_id`
`request_upload_url`	Get a pre-signed URL to upload large files (`.docx` / PDF / HTML / MD / RTF) without bloating agent context. Returns a 5-minute PUT URL plus a ready-to-run curl example — your agent shells the file directly to cloud storage, so bytes never pass through the context window. After upload, call `process_uploaded_document` with the returned `upload_id`. Max file size: 100 MB. Supported formats: `.pdf`, `.docx`, `.txt`, `.rtf`, `.md`, `.html`, `.htm`.	`filename`, `content_type`, `size_bytes`, `purpose`
`process_uploaded_document`	Parse a file uploaded via `request_upload_url` into structured HTML with chunk IDs for targeted AI editing. Same parsing pipeline as `upload_document_base64` — tables, borders, shading, alternating row colors, fonts, and inline styling preserved on edit and export. Pass `parse_mode='document'` to load as the active editable document, or `parse_mode='attachment'` to load as a read-only AI-searchable reference. Returns a compact result by default (`chunks_count`, `version_id`, `page_setup`; `html` is `null`) so the parsed body never floods agent context — pass `return_html=true` only if you actually need the HTML back. Loading a file is not billed — you’re only charged when the AI later edits it.	`upload_id`, `filename`, `session_id`, `parse_mode`, `return_html`
`export_document`	Export the current document with full fidelity. Five output formats — `docx` (default, Microsoft Word Open XML), `pdf` (paginated, print-ready), `html` (standalone with inlined CSS), `markdown` (`.md` with ATX headings), `txt` (plain text). Pass an `options` object to customise paper size, orientation, margins, filename, image embedding, and optional PDF watermarks. Non-fatal issues surface via the `X-Export-Warnings` response header. For documents over 20 MB, use the `request_upload_url` → PUT → `export_document` with `upload_id` flow.	`session_id`, `html`, `upload_id`, `format`, `options`, `filename`
`request_download_url`	Re-export the session’s current document and get a pre-signed URL to download it without proxying through the agent. Returns a 15-minute GET URL plus a curl example — your agent fetches the file directly from cloud storage. Same five formats as `export_document` (`format='pdf'` produces a native PDF); pass `options` to customise the export. Use this when the user wants to retrieve a finished document at scale.	`session_id` (required), `format`, `filename`, `options`
`upload_image_base64`	Upload an image (PNG/JPG/GIF/WebP, base64) to use inside documents — it returns a hosted URL you can reference in chat (“insert my logo at the top”). The agent-friendly way to get local image bytes into a document.	`filename`, `image_base64`, `session_id`

Sessions

Tool	Description	Key parameters
`list_sessions`	List your active document editing sessions to resume or audit prior work.	`limit`
`get_session_history`	Restore the full conversation and document state for a previous session, including chunk IDs, attachments, and editor actions. Returns the focused document’s HTML by default; pass `include_document_html=false` to skip the body and get conversation + metadata only (lighter on tokens when resuming a large document).	`session_id`, `include_document_html`
`get_session_jobs`	List all async chat jobs for a specific session, most recent first. Pass `compact=true` to omit each job’s heavy result payload (status/progress only) — useful when you just want to see which jobs are paused.	`session_id`, `limit`, `compact`
`revert_session_to_message`	Rewind a chat session to before a specific user message — restores both the document and the conversation in one call. Returns the reverted message text so you can pre-fill a compose box for editing. The original branch is preserved server-side but hidden from active reads.	`session_id`, `turn_index`
`redo_revert`	Undo a revert. Restores the session forward to the pre-revert state and brings back the rolled-back conversation and document. Pass the same `turn_index` you reverted plus the `redo_checkpoint_id` returned by that revert. Meant for use immediately after a revert, before sending a new message. The mirror of `revert_session_to_message`.	`session_id`, `turn_index`, `redo_checkpoint_id`

Session documents (multi-document)

A session can hold several open documents at once — like tabs in an editor. One document is always the focused document (the default target for chat turns that don’t specify document_id).

Tool	Description	Key parameters
`list_session_documents`	List every open document in a session — each one’s id, title, section count, page geometry, and which one is focused. Token-light by default: the HTML body is omitted unless you pass `include_html=true`. Document ids from this roster are what you pass as `document_id` on `chat`/`chat_async` — and every such parameter ALSO accepts the roster’s `durable_document_id` (the permanent Files id), so you can drive a session entirely with durable ids.	`session_id`, `include_html`
`focus_session_document`	Switch the session’s focused document. Subsequent chat turns without an explicit `document_id` target the newly focused document.	`session_id`, `document_id`
`close_session_document`	Close an open document in the session. Optionally pass `next_focus` to choose which remaining document takes focus. The session itself stays alive.	`session_id`, `document_id`, `next_focus`

Roster reads are token-light by default. list_session_documents (and the Files reads + open_documents/init_session below) return each document’s title plus metadata, but not the HTML body, by default — perfect for picking a target or labelling tabs without spending tokens. Pass include_html=true only when you actually need the document body.

Files (durable documents)

Documents in SuperDocs are durable — they persist across sessions and survive restarts, like files on disk. Open a saved document into any new session to keep working on it, rename it, or archive it when you’re done. Archiving is a soft delete: archived documents are recoverable for about 30 days, then purged.

Tool	Description	Key parameters
`list_documents`	List your durable documents (across all sessions) to find one to reopen, rename, or archive. Returns each document’s `title` and metadata by default; pass `include_html=true` for bodies.	`limit`, `include_html`
`get_document_detail`	Get one durable document by id — its `title`, metadata, and a free `structure` outline (headings with levels/positions, section count, block count, media counts, plus a `parts` list naming any page headers, footers, footnotes, endnotes, and comments with their ids) by default, or the full HTML body with `include_html=true`. `structure` is the cheap way to verify an edit landed — never export just to check.	`document_id`, `include_html`
`rename_document`	Rename a durable document. The new title is what shows up in `list_documents` and as the tab label when it’s open.	`document_id`, `title`
`archive_document`	Destructive (soft delete). Archive a durable document so it no longer appears in the active list. It’s recoverable for about 30 days, then permanently purged. Use only when the user explicitly wants the document removed. If the document is open in another session the call fails with 409 `document_in_use` (nothing archived) — re-call with `force=true` or close it there first.	`document_id`, `force`
`unarchive_document`	Restore (un-archive) a previously archived durable document so it returns to the active list. The clean inverse of `archive_document` — it takes the same durable `document_id`, so you can round-trip archive ↔ restore by id (no session needed). Idempotent — restoring an already-active document is a no-op.	`document_id`
`open_documents`	Open one or more saved durable documents into a session — like opening files into tabs. Optionally choose which one takes focus. Returns the resulting roster (`title` + metadata; `include_html=true` for bodies).	`session_id`, `document_ids`, `focus_document_id`, `include_html`
`init_session`	Create a new session and open saved durable documents into it in a single call — a shortcut for “start a fresh session with these files already loaded.”	`session_id`, `document_ids`, `focus_document_id`, `include_html`

Cross-session memory

SuperDocs can optionally carry a small durable memory note across an API key’s sessions (see the opt-in cross_session_memory field on chat/chat_async). This tool manages that note.

Tool	Description	Key parameters
`clear_cross_session_memory`	Destructive. Wipe the cross-session memory note for this API key (or for a specific end-customer when you pass `memory_key`). The note is gone permanently — the AI starts fresh on the next session that opts into cross-session memory. The parameter is named `memory_key` (pass the same value you send as `cross_session_memory_key` on chat) — omitting it clears the account-level note, so set it to target a specific end-customer.	`memory_key`

Attachments

Tool	Description	Key parameters
`upload_attachment_base64`	Upload a reference file (PDF/DOCX/image) for the AI to query while editing. Processed asynchronously; queryable via semantic search and multimodal vision.	`filename`, `file_base64`, `session_id`
`delete_attachment`	Remove an attachment from a session or cancel its in-progress processing.	`attachment_id`, `session_id`
`get_attachment_status`	Check processing status of all attachments in a session. Poll after upload to know when ready.	`session_id`

Jobs

Tool	Description	Key parameters
`list_jobs`	List your async chat jobs (in-progress, awaiting approval, completed, failed). Pass `compact=true` to omit each job’s heavy result payload and get a lightweight status/progress list.	`status`, `limit`, `compact`
`get_job`	Get the status, partial results, and any pending changes for an async chat job. Poll after `chat_async`.	`job_id`
`cancel_job`	Cancel a pending or in-progress async chat job. Already-applied changes are preserved.	`job_id`

Account

Tool	What it does	Key parameters
`get_account_status`	Your account at a glance: tier, operations used/remaining this month, reset date, and whether the account has been adopted by a human. The first thing to call when resuming work with saved credentials, and the cheapest way to budget a long job. Non-billable.	—
`request_limit_increase`	Request higher document/chat scale limits for your account in one call — use after a `413` with `DOCUMENT_TOO_COMPLEX` (single document past the standard per-document page limit) or `SESSION_TOO_FULL` (documents open in one chat past the per-chat limit). These are stability limits, not hard caps: the team is notified immediately with your account identity and the numbers you send, and limits are typically expanded within a day. Optional fields: `kind`, `attempted_pages`, `attempted_sections`, `filename`, `note`. Non-billable.	—

Running as an autonomous agent? You can create your own account and sk_ API key in one request (no web form, no human), then check quota anytime with get_account_status. When you near your monthly cap, hand the account to a human: POST /v1/agents/handoff with their email returns a one-time takeover code. They open an emailed link, enter the code, and adopt the account in place, so your work and this API key keep working. No human? POST /v1/agents/request-upgrade. Full flow (signup → handoff → adopt) is on the For AI Agents page. (Signup, handoff, adopt, and request-upgrade are REST endpoints, not MCP tools.)

Templates

Tool	Description	Key parameters
`upload_template_base64`	Save a document template (NDA, contract, SOP, letterhead) for reuse across sessions. Referenceable by the AI when drafting new documents.	`filename`, `file_base64`
`list_user_templates`	List all saved document templates available to the user or organization.	—
`delete_user_template`	Delete a saved document template by ID (soft-delete).	`template_id`

Health

Tool	Description	Key parameters
`health`	Verify the SuperDocs MCP server is reachable and serving traffic. Runs over your authenticated `/mcp/` connection like every MCP tool, so it also confirms your API key is wired up correctly (a `401` means a key problem, not downtime). The REST equivalent, `GET https://api.superdocs.app/health`, requires no authentication.	—

Two upload paths — pick by file size. For files larger than 100KB, use the pre-signed URL flow (request_upload_url → upload via curl → process_uploaded_document). Bytes stream directly to cloud storage and never pass through your agent’s context window, saving thousands of tokens per upload. For files smaller than 100KB where token cost is trivial, upload_document_base64 still works inline — encode to base64 and pass the original filename (used for file type detection). Supported file types: .pdf, .docx, .txt, .rtf, .md, .html, .htm. Maximum file size: 100 MB.

Compact response mode for editing large documents. When working with documents larger than ~20 pages, set response_mode='compact' on chat and chat_async. Instead of returning the full updated HTML on every turn (~130K tokens for a 100-page styled doc), the response includes only chunk_diffs — the per-section before/after for chunks that were actually changed. To read sections, just ask in natural language (“show me the force majeure clause”) and the AI returns the content in the reply text. A 5-turn editing session on a 100-page doc drops from ~700K tokens to ~3K tokens this way.

For full request/response schemas, open the API Reference tab in the top navigation (auto-generated from the OpenAPI spec). For copy-paste request examples, see cURL examples and the Quickstart.

Getting Started

Capabilities

Account & Billing

Core Concepts

Guides

MCP Integration

Errors & Limits

Code Examples

Available Tools

Available MCP Tools

Chat

Documents

Sessions

Session documents (multi-document)

Files (durable documents)

Cross-session memory

Attachments

Jobs

Account

Templates

Health

​Available MCP Tools

​Chat

​Documents

​Sessions

​Session documents (multi-document)

​Files (durable documents)

​Cross-session memory

​Attachments

​Jobs

​Account

​Templates

​Health

Available MCP Tools

Chat

Documents

Sessions

Session documents (multi-document)

Files (durable documents)

Cross-session memory

Attachments

Jobs

Account

Templates

Health