Available MCP Tools
When you connect to the SuperDocs MCP server, these 25 tools become available to your AI tool. Each tool is designed to surface SuperDocs’ real capabilities — structural editing of styled documents, multi-document sessions, 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”). 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. | message, session_id, document_html, document_id, model_tier, thinking_depth, approval_mode, response_mode, image_attachments |
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 as chat. For large documents, set response_mode='compact' so polled job results skip the full HTML and surface only per-section diffs. | message, session_id, document_html, document_id, model_tier, approval_mode, response_mode |
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 |
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. Counts as one billable operation. | upload_id, filename, session_id, parse_mode |
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 | Get a pre-signed URL to download an exported document without proxying through the agent. Returns a 15-minute GET URL plus a curl example — your agent fetches the file directly from cloud storage. Pair with export_document for any file the user wants to retrieve at scale. | blob_path, format |
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. | session_id |
get_session_jobs | List all async chat jobs for a specific session, most recent first. | session_id, limit |
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 |
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 — ids, content (HTML) + page geometry, and which one is focused. Document ids from this roster are what you pass as document_id on chat/chat_async. | session_id |
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 |
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). | status, limit |
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 |
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. No auth required. | — |
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.
