Suparse Document Processing

Suparse MCP Server

MCP stdio server for the Suparse Document Processing API. Use it from local MCP clients such as Claude Code and Codex to extract structured data from documents into JSON, CSV, XLSX, or Google Sheets; process single files or folders, including encrypted PDFs; let Suparse auto-detect extraction schemas or apply your team templates; create schemas automatically; split mixed multi-page documents; and download or clean up results by document ID.

Security Boundary

This is a local stdio MCP server. Connected MCP clients can ask it to read local document paths and write export files wherever the server process has permission. Only connect it to MCP clients and workspaces you trust.

Requirements

• A Suparse API key
• Node.js 20+

Authentication

The MCP server reads credentials from:

1. SUPARSE_API_KEY
2. ~/.config/suparse/config.json

Prefer passing SUPARSE_API_KEY through your client's environment or secret-input support. The fallback file is implemented by Suparse and contains { "apiKey": "your_api_key" }. Protect it as a credential file.

Replace your_api_key in the examples below. Client env settings and CLI --env options can save the key in client configuration; keep files containing real keys out of Git and shared workspaces. CLI commands containing a key may also appear in shell history. Use scoped API keys where available.

Local Installation

Install your chosen client first and ensure Node.js 20+ and npx are available to it. These setups launch @suparse/mcp as a local stdio process:

• Claude Code
• Claude Desktop
• Codex CLI / IDE
• Cursor
• VS Code / GitHub Copilot
• Gemini CLI
• Windsurf / Cascade

Merge JSON examples into existing configuration rather than replacing other servers. After connecting, use the template-listing check to verify Suparse authentication.

Claude Code

Install for all your projects with user scope:

claude mcp add --scope user --transport stdio suparse \

--env SUPARSE_API_KEY=your_api_key \ -- npx -y @suparse/mcp

Keep the server name (suparse) before --env; Claude Code can otherwise parse it as another environment variable and report Invalid environment variable format.

To change an existing registration (for example, its API key or launch command), remove it before running the add command again:

claude mcp remove --scope user suparse

Use the name and scope from your original installation. For a user-scoped local test registered as suparse-local, run claude mcp remove --scope user suparse-local. After adding the updated registration, fully exit Claude Code and start a fresh session to load the new configuration.

Check the configuration and connection:

claude mcp list

claude mcp get suparse

Inside Claude Code, use /mcp to inspect status and tools, then run the template-listing check. See the Claude Code MCP documentation.

Claude Desktop

Open your config file at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows. Add Suparse to the mcpServers section:

{

"mcpServers": { "suparse": { "command": "npx", "args": ["-y", "@suparse/mcp"], "env": { "SUPARSE_API_KEY": "your_api_key" } } } }

Fully quit and reopen Claude Desktop, confirm Suparse appears among the available tools, then run the template-listing check.

If Windows reports a process-start error for npx, replace the server's command and args with:

{

"command": "cmd", "args": ["/c", "npx", "-y", "@suparse/mcp"] }

Keep the existing env block. This workaround is only needed for clients that cannot launch npx.cmd directly.

Codex

The preferred installation is through the CLI:

codex mcp add suparse \

--env SUPARSE_API_KEY=your_api_key \ -- npx -y @suparse/mcp

After installation, add tool_timeout_sec = 300 inside the existing [mcp_servers.suparse] table in ~/.codex/config.toml. The CLI command does not set this timeout.

Alternatively, configure the server manually in ~/.codex/config.toml or a project-scoped .codex/config.toml:

[mcp_servers.suparse]

command = "npx" args = ["-y", "@suparse/mcp"] tool_timeout_sec = 300

[mcp_servers.suparse.env] SUPARSE_API_KEY = "your_api_key"

tool_timeout_sec gives Suparse extraction tools up to five minutes to finish; Codex defaults to 60 seconds. The CLI and IDE extension share this configuration. See the Codex MCP documentation.

Verify the configured server:

codex mcp list

In an interactive Codex session, use /mcp to inspect active servers, then run the template-listing check.

Cursor

Add this to ~/.cursor/mcp.json for all projects, or .cursor/mcp.json for the current project:

{

"mcpServers": { "suparse": { "type": "stdio", "command": "npx", "args": ["-y", "@suparse/mcp"], "env": { "SUPARSE_API_KEY": "${env:SUPARSE_API_KEY}" } } } }

Set SUPARSE_API_KEY in Cursor's environment before launching it; the ${env:SUPARSE_API_KEY} reference keeps the key out of the JSON file. Restart Cursor after changing its environment. Alternatively, put the key in an untracked personal configuration.

Open Cursor's MCP settings, confirm Suparse is enabled and its tools are available, then run the template-listing check in Agent chat. See the Cursor MCP documentation.

VS Code / GitHub Copilot

For Copilot CLI, install and verify with:

copilot mcp add suparse \

--env SUPARSE_API_KEY=your_api_key \ --timeout 300000 \ -- npx -y @suparse/mcp copilot mcp list

The timeout is in milliseconds and allows up to five minutes for tool discovery and calls. Then run the template-listing check in Copilot CLI. See the Copilot CLI command reference.

For a portable Copilot setup, create .mcp.json in the workspace root. For a personal installation, use ~/.copilot/mcp-config.json (or $COPILOT_HOME/mcp-config.json if configured):

{

"mcpServers": { "suparse": { "type": "stdio", "command": "npx", "args": ["-y", "@suparse/mcp"], "env": { "SUPARSE_API_KEY": "your_api_key" }, "tools": ["*"] } } }

Keep any file with a real key untracked. For a workspace configuration using VS Code's password input, use .vscode/mcp.json instead:

{

"inputs": [ { "id": "suparse-api-key", "type": "promptString", "description": "Suparse API key", "password": true } ], "servers": { "suparse": { "type": "stdio", "command": "npx", "args": ["-y", "@suparse/mcp"], "env": { "SUPARSE_API_KEY": "${input:suparse-api-key}" } } } }

The VS Code format uses servers; the portable format uses mcpServers. Choose one setup to avoid duplicate servers. Interactive inputs are not forwarded to Copilot harness sessions; use the portable setup for those sessions.

Run MCP: List Servers from the Command Palette, select Suparse and start it, then run the template-listing check in agent chat. See the VS Code MCP configuration reference.

Gemini CLI

Install for your user account:

gemini mcp add --scope user \

--env SUPARSE_API_KEY=your_api_key \ suparse npx -y @suparse/mcp

This writes the server configuration to ~/.gemini/settings.json. Check connection status with:

gemini mcp list

In an interactive session, use /mcp list to inspect tools, then run the template-listing check. See the Gemini CLI MCP documentation.

Windsurf / Cascade

These instructions target the legacy Cascade agent. For the newer default Devin Local agent, follow the Devin CLI MCP configuration documentation; its configuration locations and migration behavior depend on the installed version, even where paths overlap with Cascade.

Open the MCP configuration from Cascade's MCP controls. Windsurf installations use ~/.codeium/windsurf/mcp_config.json (%USERPROFILE%\.codeium\windsurf\mcp_config.json on Windows). Cascade in current Devin Desktop releases uses ~/.config/devin/mcp_config.json (or $XDG_CONFIG_HOME/devin/mcp_config.json) on macOS/Linux and %APPDATA%\devin\mcp_config.json on Windows. Opening the file from Cascade selects the path for your installed version.

Add Suparse under mcpServers:

{

"mcpServers": { "suparse": { "command": "npx", "args": ["-y", "@suparse/mcp"], "env": { "SUPARSE_API_KEY": "your_api_key" } } } }

Save the file, refresh the MCP list or restart the client, and confirm Suparse and its tools are enabled in Cascade. Run the template-listing check. See the Cascade MCP documentation.

Verify Your Installation

In your client's agent chat, ask:

Use Suparse's list_templates tool to list my team's available extraction templates.

Approve the tool call if prompted. A successful response confirms both the MCP connection and Suparse API authentication; an empty team_templates list is valid if your team has no templates. This check does not upload or process a document.

If the server fails to start, check that Node.js 20+ and npx are on the client's PATH, and inspect its MCP logs. For authentication errors, check the key passed to the server or the Suparse fallback file. Desktop applications may not inherit environment variables set in a terminal.

Verify Document Processing (Optional)

Processing may consume Suparse credits. Use a small sample invoice or receipt containing data you are comfortable uploading to Suparse.

1. Put the sample PDF somewhere accessible to the MCP server and use its absolute path (see local paths).
2. Ask your client: "Use Suparse's start_file_extraction to extract structured data from /absolute/path/to/sample.pdf. Return the task ID and any document IDs or processing status provided. Do not delete the uploaded document."
3. Call wait_for_task_extraction with the returned task ID. If processing is still running, retain the ID and poll again; do not upload the file again.
4. Once processing completes, use a returned document ID to call fetch_document_result. If necessary, use get_task_results with the task ID to discover document IDs.

This checks local file access, authentication, upload, processing, and result retrieval. Keep the uploaded document unless you explicitly want to delete it later.

Tools

defer uploads and polls until processing reach