docuprox-mcp

MCP (Model Context Protocol) server for the DocuProx document-processing API. Exposes DocuProx as tools that any MCP-compatible AI client can call — Claude Desktop, Claude Code, Cursor, Windsurf, and more.

Quickstart (npx — no install required)

DOCUPROX_API_KEY=your_key DOCUPROX_BASE_URL=https://api.docuprox.com/v1 npx docuprox-mcp

Requires Node.js ≥ 18.

Configuration

| Variable | Required | Description | |---------------------|----------|--------------------------| | DOCUPROX_API_KEY | yes | Your DocuProx API key | | DOCUPROX_BASE_URL | yes | Base URL of the DocuProx API (e.g. https://api.docuprox.com/v1) |

Connect to an MCP Client

Claude Desktop

macOS — ~/Library/Application Support/Claude/claude_desktop_config.json
Windows — %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "docuprox": {
      "command": "npx",
      "args": ["docuprox-mcp"],
      "env": {
        "DOCUPROX_API_KEY": "your_api_key_here",
        "DOCUPROX_BASE_URL": "https://api.docuprox.com/v1"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add docuprox -e DOCUPROX_API_KEY=your_api_key_here -e DOCUPROX_BASE_URL=https://api.docuprox.com/v1 -- npx docuprox-mcp

Cursor / Windsurf

Add to your MCP settings (.cursor/mcp.json or equivalent):

{
  "mcpServers": {
    "docuprox": {
      "command": "npx",
      "args": ["docuprox-mcp"],
      "env": {
        "DOCUPROX_API_KEY": "your_api_key_here",
        "DOCUPROX_BASE_URL": "https://api.docuprox.com/v1"
      }
    }
  }
}

Available Tools

process_job

Submit a document for asynchronous processing. Returns a job_id to track with poll_job or job_results.

| Argument | Type | Required | Description | |-----------------------|--------|----------|------------------------------------------------------| | file_path | string | yes | Path to file on disk (jpg, png, pdf, zip) | | template_id | string | no | UUID of a DocuProx template | | document_type | string | no* | Document category — required when no template_id | | prompt_json | object | no | Custom extraction schema | | custom_instructions | string | no | Free-text guidance for the AI | | static_values | object | no | Key-value overrides for STATIC template placeholders |

Example: "Submit the invoice at /tmp/invoice.pdf using template 123e4567-e89b-12d3-a456-426614174000"

process_agent

Submit a document for synchronous extraction. Blocks until done and returns results directly — no polling needed. Credits are automatically refunded on failure.

| Argument | Type | Required | Description | |-----------------------|--------|----------|--------------------------------------| | file_path | string | yes | Path to file on disk | | prompt_json | object | yes | Extraction schema | | document_type | string | yes | Document category | | custom_instructions | string | no | Free-text guidance | | static_values | object | no | Key-value STATIC overrides |

Example: "Extract passport data from /home/user/passport.jpg. Use document_type='passport' and prompt_json { 'name': 'full name', 'dob': 'date of birth' }"

job_status

Check the status of an async job.

| Argument | Type | Required | Description | |----------|--------|----------|-------------------------| | job_id | string | yes | UUID from process_job |

Returns: { job_id, status } where status is one of: NEW → UNZIP FILE → UNZIP FILE SUCCESS / UNZIP FILE FAILED → PROCESS IMAGE → PROCESS IMAGE SUCCESS / PROCESS IMAGE FAILED → SUCCESS / FAILED

poll_job

Block until a job finishes (or times out). Retries job_status internally on a timer.

| Argument | Type | Required | Default | Description | |---------------|--------|----------|----------|-------------------------| | job_id | string | yes | — | UUID from process_job | | interval_ms | number | no | 3000 | Poll interval in ms | | timeout_ms | number | no | 300000 | Max wait in ms (5 min) |

Example: "Submit /tmp/batch.zip then wait for the result" — Claude will call process_job then poll_job automatically.

job_results

Fetch the extracted results of a completed async job.

| Argument | Type | Required | Default | Description | |-----------------|--------|----------|----------|------------------------------------------| | job_id | string | yes | — | UUID from process_job | | result_format | string | no | "json" | Output format: "json" or "csv" |

Example: "Get the results for job 0869d5ec-5cfe-4960-878d-8b4ec1900726 in CSV format"

How File Uploads Work

Every tool that accepts a file_path:

1. Resolves it to an absolute path
2. Reads the file into a Buffer
3. Detects MIME type from the file extension
4. Sends it as multipart/form-data with field name actual_image

The AI never sees or handles base64 — just pass a local file path.

Error Handling

| Error | Cause | |-------|-------| | File not found | file_path does not exist — a clear message with the resolved path is returned | | API error | HTTP status + response body surfaced in the tool result | | Invalid arguments | Zod validation fires before any API call | | Credit failure | 402/403 from /process-agent surfaced clearly |

Local Development

# Clone and install
git clone <repo>
cd docuprox-mcp
npm install

# Run in dev mode (no build step)
DOCUPROX_API_KEY=test DOCUPROX_BASE_URL=http://localhost:5000/v1 npm run dev

# Build
npm run build

# Inspect with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

Project Structure

docuprox-mcp/
├── index.ts        ← MCP server entry point (stdio transport)
├── config.ts       ← Env-var config loader
├── client.ts       ← Axios API client (multipart/form-data uploads)
├── tools.ts        ← Zod schemas + MCP tool definitions
├── handlers.ts     ← Maps tool names → client calls
├── package.json
└── tsconfig.json

License

MIT