Suparse MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

Start Folder Extraction

start_folder_extraction

Initiate background extraction for supported files directly in a local folder, ignoring subfolders, returning task IDs per upload without waiting for processing.

Instructions

Start background extraction of sorted supported files directly inside a local folder, skipping directories and subfolders. Returns one task_id per confirmed upload without waiting for processing or exporting. At most 10 uploads run concurrently. Use wait_for_task_extraction for each task, then fetch or download results using its document IDs. Uploads may consume credits. Inspect failed entries and recovery IDs before retrying; cancellation prevents new uploads, but submitted tasks may still run. Entries marked unstarted were not uploaded. auto_approve defaults true; false requests human review, which MCP cannot perform or approve.

Input Schema

TableJSON Schema

Name	Required	Description
`split`	No	Enable auto-splitting of multi-page documents with mixed document types.
`api_url`	No
`folder_id`	No	Optional remote Suparse folder ID to assign to uploaded documents.
`folder_path`	Yes	Path to a local folder on the machine running this MCP server, not a remote Suparse folder ID. Scans supported files directly inside it, nonrecursively. Prefer an absolute path; relative paths use the server's working directory and ~ is not expanded.
`template_id`	No	Optional extraction template ID. Use only a non-system team template ID from list_templates. System template IDs are discovery-only and cannot be passed directly. Omit to let Suparse auto-detect, or use an authorized quick-schema workflow to create a team template.
`auto_approve`	No	Automatically approve extracted documents. Defaults to true. Set false only when human review is requested; use a start-only extraction tool to retain the task ID. MCP cannot approve documents, and combined extraction may time out while review is pending.
`pdf_password`	No	Optional password for an encrypted PDF. Treat this as a secret; it is used only for the upload and is not returned in results.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`total`	Yes
`failed`	Yes
`cancelled`	No
`succeeded`	Yes
`failed_count`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.5.0Oct 20, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond annotations: 10 concurrent upload cap, non-blocking return of one task_id per confirmed upload, credit consumption, cancellation only preventing new uploads while submitted tasks may still run, unstarted entries meaning not uploaded, and the auto_approve/human-review limitation that MCP cannot approve. These are exactly the operational traits an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose and return behavior, then packs concurrency, credits, retry, and cancellation caveats into few sentences with no filler. Dense but each sentence carries operational weight; minor strain from cramming several caveats into the tail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists so return values need not be explained, yet the description still notes the async task_id-per-upload contract. Combined with annotations and near-complete schema coverage, an agent has everything needed to invoke this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 86%, so baseline is 3, but the description adds real meaning for auto_approve (default true, false triggers human review MCP cannot perform) and reinforces folder_path/credit implications. It does not clarify split, template_id, or pdf_password beyond what the schema already documents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Start background extraction') plus the exact scope: supported files directly inside a local folder, skipping directories and subfolders. The nonrecursive local-folder framing distinguishes it from sibling file/folder extraction tools without needing the schema open.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit follow-up workflow ('use wait_for_task_extraction for each task, then fetch or download results using its document IDs') and a retry precondition (inspect failed entries and recovery IDs before retrying). It does not explicitly contrast with extract_folder or start_file_extraction, so routing among the extraction starters still takes some inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server