> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superdocs.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Available Tools
> All 38 MCP tools available when connecting to the SuperDocs MCP server.
# 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](/introduction/agent-signup) 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](/examples/curl) and the [Quickstart](/introduction/quickstart).