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.

Related MCP server: MCP Server for CAP

Configuration

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.

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.

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.

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.

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.

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

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