Suparse MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

Fetch JSON Results

fetch_json_results

Export selected Suparse document IDs as task-grouped JSON into the MCP response. Retrieve extraction results directly when you need JSON only, not files or ZIP artifacts.

Instructions

Export one or more existing Suparse document IDs as JSON into the MCP response, grouped by task in results (task_id, original_file, total_documents_extracted, documents). Use fetch_document_result for a direct single-document read without submitting an export; use download_results for large results, local files, CSV, XLSX, or Google Sheets. This tool only exports JSON and does not unpack ZIP artifacts. On export timeout, retain export_job_id for the export-job tools or replay the identical export with its retained idempotency_key. Does not delete documents; cleanup is explicit through delete_documents.

Input Schema

Name	Required	Description
`api_url`	No
`export_type`	No	Defaults to unified. JSON currently has the same task-group shape for original and unified.
`document_ids`	Yes	Suparse document IDs to export.
`idempotency_key`	No	Optional UUID idempotency key. Retain this key and replay the identical document IDs, format, export type, and layout if submission confirmation is lost.
`wait_timeout_ms`	No	Maximum time in milliseconds to wait for an accepted export job to complete; defaults to 60000. This bounds completion waiting, including polling retries, not submission or transfer. Allow enough total time in the MCP client for all phases.

Output Schema

Name	Required	Description	Default
`format`	Yes
`results`	Yes
`export_type`	Yes
`export_job_id`	No
`idempotency_key`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 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"
```

changedInput schema / properties / export_type / description

Previous value: -"Export mode for JSON results. Defaults to unified."New value: +"Defaults to unified. JSON currently has the same task-group shape for original and unified."

addedInput schema / properties / idempotency_key

Added value: +{
+  "description": "Optional UUID idempotency key. Retain this key and replay the identical document IDs, format, export type, and layout if submission confirmation is lost.",
+  "format": "uuid",
+  "type": "string"
+}

addedInput schema / properties / wait_timeout_ms

Added value: +{
+  "description": "Maximum time in milliseconds to wait for an accepted export job to complete; defaults to 60000. This bounds completion waiting, including polling retries, not submission or transfer. Allow enough total time in the MCP client for all phases.",
+  "exclusiveMinimum": 0,
+  "type": "integer"
+}

addedOutput schema / properties / export_job_id
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / idempotency_key
```
Added value: +{
+  "type": "string"
+}
```

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 only cover readOnly=false, destructive=false, openWorld=true, so the description carries real weight and does: it discloses the timeout fallback (retain export_job_id or replay with the retained idempotency_key), confirms no document deletion, and points cleanup at delete_documents. This is behavioral context well beyond the annotations and consistent with them.

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-loaded with what the tool does before the routing guidance, and every sentence carries a distinct rule (alternatives, format limits, timeout recovery, deletion boundary). It is dense and runs long, but no sentence is filler.

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?

With an output schema present, the description needn't explain return values, and it doesn't. Between the annotations, the rich schema, and the description's coverage of alternatives, format limits, timeout recovery, and delete semantics, 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 80% and the schema documents export_type defaults and wait_timeout_ms semantics thoroughly. The description adds meaning the schema does not, specifically the retention/replay contract for export_job_id and idempotency_key, which is the key parameter concern for this tool.

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?

The description names a specific verb (export) and resource (existing Suparse document IDs) and states the output shape (grouped by task in results with named fields). It also explicitly contrasts itself with fetch_document_result and download_results, so an agent can distinguish this tool from its closest siblings without opening any schema.

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?

It gives explicit routing rules: use fetch_document_result for a direct single-document read, use download_results for large results, local files, CSV, XLSX, or Google Sheets. It also states a negative boundary ('only exports JSON and does not unpack ZIP artifacts'), which prevents misselection for those cases.

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

Deploy Server