Suparse MCP Server

Official

by suparse

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

Extract Folder

extract_folder

Destructive

Process supported files directly inside a local folder through Suparse, uploading each document and returning task status and document IDs without scanning subfolders.

Instructions

Process sorted, immediate supported files in a local folder through Suparse (nonrecursive; directories are skipped). Defaults to result_mode defer: upload and wait for each task, retaining task status and document IDs. For task IDs before processing finishes, use start_folder_extraction. At most 10 files run concurrently. auto_approve defaults true; false requests human review, and this combined tool may wait and time out while review is pending. return_json preserves per-input task status and document IDs, reports partial tasks and empty exports as incomplete, and preserves exported data. cleanup is best-effort, allowed only with return_json, and requires a completed task and an export covering every requested document.

Input Schema

Name	Required	Description	Default
`split`	No	Enable auto-splitting of multi-page documents with mixed document types.
`api_url`	No
`cleanup`	No	Defaults to false. Set true only when remote deletion is requested. Only valid with result_mode return_json. Deletes Suparse documents only for fully completed tasks with JSON exports covering every requested document, after all workers settle. Cleanup is skipped after cancellation. Later exports cannot use deleted document IDs.
`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.
`result_mode`	No	Defaults to defer: upload and wait for processing, then return task status and document IDs without exporting. Defer does not mean background processing; use a start-only tool for that. return_json additionally exports full JSON into the MCP response and can consume substantial context. Use download_results to save large results or other export formats.	defer
`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.
`wait_timeout_ms`	No	For return_json, milliseconds to wait for each export to complete; defaults to 60000. Submission and transfer are separate phases. Ignored in defer mode.

Output Schema

Name	Required	Description	Default
`tasks`	No
`total`	Yes
`failed`	Yes
`cleanup`	No
`exports`	No
`guidance`	No
`cancelled`	No
`succeeded`	Yes
`result_mode`	Yes
`failed_count`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed21 schema fields changedv1.5.0Oct 20, 2026

removedInput schema / properties / api_url / description

Removed value: -"Optional API base URL. Defaults to SUPARSE_API_URL or Suparse production API."

removedInput schema / properties / api_url / format
```
Removed value: -"uri"
```
addedInput schema / properties / api_url / not
```
Added value: +{}
```
removedInput schema / properties / api_url / type
```
Removed value: -"string"
```

addedInput schema / properties / auto_approve

Added value: +{
+  "description": "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.",
+  "type": "boolean"
+}

changedInput schema / properties / cleanup / description

Previous value: -"Only valid with result_mode return_json. Deletes processed Suparse documents after JSON results are returned, so later exports cannot be fetched from those document IDs."New value: +"Defaults to false. Set true only when remote deletion is requested. Only valid with result_mode return_json. Deletes Suparse documents only for fully completed tasks with JSON exports covering every requested document, after all workers settle. Cleanup is skipped after cancellation. Later exports cannot use deleted document IDs."

addedInput schema / properties / folder_id

Added value: +{
+  "description": "Optional remote Suparse folder ID to assign to uploaded documents.",
+  "minLength": 1,
+  "type": "string"
+}

changedInput schema / properties / folder_path / description

Previous value: -"Local folder containing supported document files."New value: +"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."

addedInput schema / properties / pdf_password

Added value: +{
+  "description": "Optional password for an encrypted PDF. Treat this as a secret; it is used only for the upload and is not returned in results.",
+  "maxLength": 256,
+  "minLength": 1,
+  "type": "string"
+}

changedInput schema / properties / result_mode / description

Previous value: -"Controls whether extraction results in json format are returned directly. Use return_json only when you need the full JSON extraction in the MCP response. In all other cases you can retrieve the results in format of choice using download_results"New value: +"Defaults to defer: upload and wait for processing, then return task status and document IDs without exporting. Defer does not mean background processing; use a start-only tool for that. return_json additionally exports full JSON into the MCP response and can consume substantial context. Use download_results to save large results or other export formats."

changedInput schema / properties / template_id / description

Previous value: -"Optional extraction template ID. Use only a non-system team template ID from list_templates. Do not pass system template IDs directly; ask the user to add the matching system template to their templates first. Omit to let Suparse auto-detect."New value: +"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."

addedInput schema / properties / wait_timeout_ms

Added value: +{
+  "description": "For return_json, milliseconds to wait for each export to complete; defaults to 60000. Submission and transfer are separate phases. Ignored in defer mode.",
+  "exclusiveMinimum": 0,
+  "type": "integer"
+}

addedOutput schema / properties / cancelled
```
Added value: +{
+  "type": "boolean"
+}
```

addedOutput schema / properties / cleanup

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "deleted_document_ids": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "retained_document_ids": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "status": {
+      "enum": [
+        "succeeded",
+        "failed",
+        "skipped"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "status",
+    "deleted_document_ids",
+    "retained_document_ids"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / exports

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "export_job_id": {
+        "type": "string"
+      },
+      "file_path": {
+        "type": "string"
+      },
+      "idempotency_key": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "file_path"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / properties / failed / items / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "error": {
-        "type": "string"
-      },
-      "file_path": {
-        "type": "string"
-      },
-      "task_id": {
-        "type": [
-          "string",
-          "null"
-        ]
-      }
-    },
-    "required": [
-      "file_path",
-      "task_id",
-      "error"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": false,
-    "properties": {
-      "error": {
-        "type": "string"
-      },
-      "file": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "file",
-      "error"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "cancelled": {
+        "type": "boolean"
+      },
+      "code": {
+        "type": "string"
+      },
+      "error": {
+        "type": "string"
+      },
+      "error_type": {
+        "type": "string"
+      },
+      "file_path": {
+        "type": "string"
+      },
+      "meta": {
+        "additionalProperties": {},
+        "type": "object"
+      },
+      "next_action": {
+        "type": "string"
+      },
+      "partial_result": {},
+      "reason": {
+        "type": "string"
+      },
+      "recovery": {
+        "additionalProperties": false,
+        "properties": {
+          "export_job_id": {
+            "type": "string"
+          },
+          "export_request": {
+            "additionalProperties": false,
+            "properties": {
+              "document_ids": {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "export_type": {
+                "enum": [
+                  "original",
+                  "unified"
+                ],
+                "type": "string"
+              },
+              "format": {
+                "enum": [
+                  "json",
+                  "csv",
+                  "xlsx",
+                  "google_sheets"
+                ],
+                "type": "string"
+              },
+              "xlsx_layout": {
+                "enum": [
+                  "standard",
+                  "flat"
+                ],
+                "type": "string"
+              }
+            },
+            "required": [
+              "document_ids",
+              "format",
+              "export_type"
+            ],
+            "type": "object"
+          },
+          "idempotency_key": {
+            "type": "string"
+          },
+          "job": {
+            "additionalProperties": false,
+            "properties": {
+              "artifact": {
+                "anyOf": [
+                  {
+                    "additionalProperties": false,
+                    "properties": {
+                      "checksum_sha256": {
+                        "type": "string"
+                      },
+                      "content_type": {
+                        "type": "string"
+                      },
+                      "filename": {
+                        "type": "string"
+                      },
+                      "size_bytes": {
+                        "type": "number"
+                      }
+                    },
+                    "required": [
+                      "filename",
+                      "content_type",
+                      "size_bytes",
+                      "checksum_sha256"
+                    ],
+                    "type": "object"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "attempt_count": {
+                "type": "number"
+              },
+              "created_at": {
+                "type": "string"
+              },
+              "effective_artifact_format": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "error": {
+                "anyOf": [
+                  {
+                    "additionalProperties": false,
+                    "properties": {
+                      "code": {
+                        "type": "string"
+                      },
+                      "message": {
+                        "type": "string"
+                      },
+                      "meta": {
+                        "additionalProperties": {},
+                        "type": "object"
+                      },
+                      "retry_after_seconds": {
+                        "type": [
+                          "number",
+                          "null"
+                        ]
+                      }
+                    },
+                    "required": [
+                      "code",
+                      "message"
+                    ],
+                    "type": "object"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "expired_at": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "expires_at": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "export_job_id": {
+                "type": "string"
+              },
+              "export_type": {
+                "type": "string"
+              },
+              "generated_count": {
+                "type": "number"
+              },
+              "initial_excluded_count": {
+                "type": "number"
+              },
+              "initial_exportable_count": {
+                "type": "number"
+              },
+              "replayed": {
+                "type": "boolean"
+              },
+              "requested_by_user_email": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "requested_by_user_id": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "requested_by_user_name": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "requested_count": {
+                "type": "number"
+              },
+              "requested_format": {
+                "type": "string"
+              },
+              "runtime_excluded_count": {
+                "type": "number"
+              },
+              "status": {
+                "type": "string"
+              },
+              "total_matching_count": {
+                "type": "number"
+              },
+              "xlsx_layout": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            },
+            "required": [
+              "export_job_id",
+              "status",
+              "requested_format",
+              "effective_artifact_format",
+              "export_type",
+              "xlsx_layout",
+              "created_at",
+              "expired_at",
+              "requested_by_user_id",
+              "requested_by_user_name",
+              "requested_by_user_email",
+              "requested_count",
+              "total_matching_count",
+              "initial_exportable_count",
+              "initial_excluded_count",
+              "generated_count",
+              "runtime_excluded_count",
+              "attempt_count",
+              "expires_at",
+              "artifact",
+              "error",
+              "replayed"
+            ],
+            "type": "object"
+          },
+          "last_status": {
+            "type": "string"
+          },
+          "operation_may_be_running": {
+            "type": "boolean"
+          },
+          "source_upload_id": {
+            "type": "string"
+          },
+          "storage_status_code": {
+            "type": "number"
+          },
+          "task_id": {
+            "type": "string"
+          },
+          "upload_batch_id": {
+            "type": "string"
+          },
+          "upload_reference_id": {
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "retry_after_seconds": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "status_code": {
+        "type": "number"
+      },
+      "task_id": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "unstarted": {
+        "type": "boolean"
+      }
+    },
+    "required": [
+      "file_path",
+      "task_id",
+      "error"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": false,
+    "properties": {
+      "cancelled": {
+        "$ref": "#/properties/failed/items/anyOf/0/properties/cancelled"
+      },
+      "code": {
+        "$ref": "#/properties/failed/items/anyOf/0/properties/code"
+      },
+      "error": {
+        "type": "string"
+      },
+      "error_type": {
+        "$ref": "#/properties/failed/items/anyOf/0/properties/error_type"
+      },
+      "file": {
+        "type": "string"
+      },
+      "meta": {
+        "$ref": "#/properties/failed/items/anyOf/0/properties/meta"
+      },
+      "next_action": {
+        "$ref": "#/properties/failed/items/anyOf/0/properties/next_action"
+      },
+      "partial_result": {
+        "$ref": "#/properties/failed/items/anyOf/0/properties/partial_result"
+      },
+      "reason": {
+        "$ref": "#/properties/failed/items/anyOf/0/properties/reason"
+      },
+      "recovery": {
+        "$ref": "#/properties/failed/items/anyOf/0/properties/recovery"
+      },
+      "retry_after_seconds": {
+        "$ref": "#/properties/failed/items/anyOf/0/properties/retry_after_seconds"
+      },
+      "status_code": {
+        "$ref": "#/properties/failed/items/anyOf/0/properties/status_code"
+      },
+      "unstarted": {
+        "$ref": "#/properties/failed/items/anyOf/0/properties/unstarted"
+      }
+    },
+    "required": [
+      "file",
+      "error"
+    ],
+    "type": "object"
+  }
+]

addedOutput schema / properties / failed_count
```
Added value: +{
+  "type": "number"
+}
```
addedOutput schema / properties / guidance
```
Added value: +{
+  "type": "string"
+}
```

changedOutput schema / properties / succeeded / items / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "document_ids": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "file_path": {
-        "type": "string"
-      },
-      "task_id": {
-        "type": "string"
-      }
-    },
-    "required": [
-      "file_path",
-      "task_id",
-      "document_ids"
-    ],
-    "type": "object"
-  },
-  {
-    "additionalProperties": true,
-    "properties": {
-      "documents": {
-        "items": {},
-        "type": "array"
-      },
-      "original_file": {
-        "type": "string"
-      },
-      "task_id": {
-        "type": "string"
-      },
-      "total_documents_extracted": {
-        "type": "number"
-      }
-    },
-    "required": [
-      "task_id",
-      "original_file",
-      "total_documents_extracted",
-      "documents"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "document_ids": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "file_path": {
+        "type": "string"
+      },
+      "status": {
+        "type": "string"
+      },
+      "task_id": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "file_path",
+      "task_id",
+      "document_ids"
+    ],
+    "type": "object"
+  },
+  {
+    "additionalProperties": true,
+    "properties": {
+      "documents": {
+        "items": {},
+        "type": "array"
+      },
+      "original_file": {
+        "type": "string"
+      },
+      "task_id": {
+        "type": "string"
+      },
+      "total_documents_extracted": {
+        "type": "number"
+      }
+    },
+    "required": [
+      "task_id",
+      "original_file",
+      "total_documents_extracted",
+      "documents"
+    ],
+    "type": "object"
+  }
+]

addedOutput schema / properties / tasks

Added value: +{
+  "items": {
+    "$ref": "#/properties/succeeded/items/anyOf/0"
+  },
+  "type": "array"
+}

changedOutput schema / required

Previous value: -[
-  "result_mode",
-  "total",
-  "succeeded",
-  "failed"
-]New value: +[
+  "result_mode",
+  "total",
+  "succeeded",
+  "failed",
+  "failed_count"
+]

First observedv1.3.0Jul 30, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations give safety hints (destructive, open-world, non-idempotent), and the description adds substantive context beyond them: concurrency cap of 10, the default defer behavior, the timeout risk while human review is pending, cleanup being best-effort and constrained, and that partial tasks/empty exports are reported as incomplete.

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?

Main purpose and scope are front-loaded in the first sentence, and each sentence carries distinct operational information. It is dense and clause-heavy for a 10-parameter tool, but little of it is wasted.

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?

For a complex 10-parameter tool with an output schema and mutating side effects, the description covers modes, timing, approval, cleanup constraints, and separation of concerns. An agent has enough to invoke it correctly; return values are handled by the output schema.

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 90%, so the schema carries most burden (baseline 3). The description nonetheless adds cross-parameter meaning the schema doesn't fully convey, such as result_mode's defer-vs-background distinction and the fact that cleanup is only valid with return_json and a fully covering export.

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 (process), resource (sorted immediate supported files in a local folder), and scope (nonrecursive, directories skipped). It explicitly names the sibling start_folder_extraction and the condition that routes to it, so the agent can distinguish it without opening schemas.

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

Usage Guidelines5/5

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

Provides explicit when-to-use guidance: defer vs return_json semantics, use start_folder_extraction for task IDs before processing completes, and download_results for large results. It also states exactly when cleanup is permitted and when auto_approve=false applies, covering alternatives and conditions.

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

Deploy Server