Suparse MCP Server

Official

by suparse

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

Extract File

extract_file

Destructive

Extract structured data from one local document: upload it to Suparse, wait for processing, and return task/document IDs for later export.

Instructions

Process one local file through Suparse. Defaults to result_mode defer: upload, wait for terminal processing, and return task_id/document_ids for later export. A partially_completed task retains its status. For an immediate task ID, use start_file_extraction, then wait_for_task_extraction and get_task_results. 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.
`file_path`	Yes	Path to a local document on the machine running this MCP server, not a URL or chat attachment. Supported extensions: .pdf, .jpg, .jpeg, .png, .heic, .heif. Prefer an absolute path; relative paths use the server's working directory and ~ is not expanded.
`folder_id`	No	Optional remote Suparse folder ID to assign to uploaded documents.
`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."

changedInput schema / properties / file_path / description

Previous value: -"Local path to a supported document file."New value: +"Path to a local document on the machine running this MCP server, not a URL or chat attachment. Supported extensions: .pdf, .jpg, .jpeg, .png, .heic, .heif. Prefer an absolute path; relative paths use the server's working directory and ~ is not expanded."

addedInput schema / properties / folder_id

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

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.5/5.0

Behavior5/5

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

Adds substantial context beyond the annotations: partial tasks retain status, auto_approve=false can cause the combined tool to wait and time out during human review, return_json consumes context and reports partial/empty exports as incomplete, and cleanup is best-effort, return_json-only, and gated on a completed task with full export coverage. This explains the destructiveHint behavior (remote document deletion) rather than contradicting it.

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 the default behavior before alternatives, and every sentence carries operational content. Sentences are long and dense for a 10-parameter tool, but there is little filler.

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

Completeness4/5

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

Covers the key ambiguities of a combined extract-and-wait tool (partial tasks, approval timeouts, export vs. defer, cleanup constraints), and an output schema exists so return-value detail is not needed. Minor gaps remain around resumed exports and how defer results feed later export steps.

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 90%, so the schema already documents most parameters; the description nonetheless adds meaning about result_mode defaults, the defer/return_json behavioral difference, wait_timeout_ms applying per-export in JSON mode, and cleanup's preconditions. It adds value but largely restates schema-documented semantics.

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+resource+scope: 'Process one local file through Suparse,' with the default flow spelled out (upload, wait for terminal processing, return task_id/document_ids). This cleanly separates it from extract_folder and the start_file_extraction/wait_for_task_extraction pipeline.

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?

Explicitly routes to alternatives: use start_file_extraction for an immediate task ID, and download_results for large results or other export formats. It also warns that result_mode defer 'does not mean background processing.' It stops short of a full when-to-prefer-this-over-the-start-only-pipeline statement, but the context is clear.

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

Deploy Server