MCP Integration Guide

The DocPurify MCP Server lets MCP Hosts such as Claude Desktop, Cursor, and Codex call DocPurify document processing capabilities directly. You only need to create one MCP Key and paste the configuration below into your client.

Note
MCP can now upload local files directly with upload_document_file. Use submit_document_for_processing only when you already have a DocPurify file_id.

MCP Host
  -> DocPurify MCP stdio server
  -> DocPurify service
  -> Document processing jobs and results

1. 5-minute quick setup

You only need two things:

Add the Server configuration below to your MCP Host. In most cases, the only value you need to replace is DOCPURIFY_MCP_KEY.

{
  "mcpServers": {
    "docpurify": {
      "command": "npx",
      "args": ["-y", "@docpurify/mcp-server"],
      "env": {
        "DOCPURIFY_MCP_KEY": "dp_your_mcp_key"
      }
    }
  }
}

Save the configuration and restart the MCP Host. After initialize, the client will discover DocPurify tools through tools/list.

2. Currently supported capabilities

DocPurify currently exposes Tools only. Resources and Prompts are not available yet.

Typical use cases:

• Let an AI assistant inspect workspace state, credits, and recent jobs.
• Upload a local file from the MCP host and start processing in one step.
• Start processing for an already uploaded file by using its file_id.
• Poll a document job until result_ready = true.
• Fetch Markdown output and download links after processing completes.
• Cancel a job that is still queued or processing.

3. Protocol and transport

The DocPurify MCP Server uses standard MCP stdio transport. The MCP Host starts a local process and exchanges JSON-RPC messages through stdin/stdout.

Security reminder
In stdio mode, never put the Key into prompts or tool descriptions. Pass it only through the MCP Host env configuration.

4. Create and store an API Key

MCP API Keys are managed on the MCP page in the DocPurify web console:

1. Sign in to DocPurify.
2. Open the MCP page from the main navigation.
3. Create an API Key.
4. Save the generated Key immediately. The full Key is not shown again after you leave the page.
5. Put the Key in DOCPURIFY_MCP_KEY inside your MCP Host configuration.

Current rules:

• One account can keep only one active MCP API Key at a time.
• Rotating the Key issues a new Key immediately and revokes the old one.
• Revoking the Key causes every MCP call using that Key to fail.
• Web login is only used to manage Keys and cannot replace MCP request authentication.

5. Client configuration examples

Claude Desktop, Cursor, Codex, and other clients store MCP configuration in different files, but the core fields are always command, args, and env.

{
  "mcpServers": {
    "docpurify": {
      "command": "npx",
      "args": ["-y", "@docpurify/mcp-server"],
      "env": {
        "DOCPURIFY_MCP_KEY": "dp_your_mcp_key",
        "DOCPURIFY_MCP_TIMEOUT_SECONDS": "30"
      }
    }
  }
}

Configuration notes:

• DOCPURIFY_MCP_TIMEOUT_SECONDS is optional and defaults to 30 seconds.
• If the client machine does not have Node.js, install Node.js 18 or newer first.
• Fully restart the client after saving the configuration so the MCP Server reloads environment variables.
• If your client supports “Reload MCP servers,” you can refresh the server list directly.

6. Recommended call order

For a first integration, this sequence is recommended:

1. Create or confirm the current active Key in the web console.
2. Start the MCP Host and confirm it can discover the docpurify Server.
3. Call get_workspace_overview to inspect account context, credits, and recent jobs.
4. If you have a local file path, call upload_document_file.
5. Only use submit_document_for_processing for advanced workflows where a valid file_id already exists.
6. Poll progress with get_document_job.
7. Only call get_document_result when result_ready = true.
8. To stop a job, check the current status first and then call cancel_document_job.
9. To clean up data, call delete_document_job only for a terminal job.

7. Tools reference

7.1 Tool parameter tables

get_workspace_overview

Description: Read workspace summary, including credits, storage usage, recent jobs, alerts, and recommended next actions.

upload_document_file

Description: Default entry point for end-user workflows. Upload a local file and start processing.

Advanced/internal fields supported but usually unnecessary for normal users: content_page_count, toc_page_count, toc_has_annotations, image_count, text_validation, image_validation, output_format.

submit_document_for_processing

Description: Advanced entry point for workflows that already have a valid file_id.

For ordinary users, prefer upload_document_file instead of this tool.

list_document_jobs

Description: List recent document jobs for the current account, optionally filtered by status.

get_document_job

Description: Read one document job in detail, including status, progress, current stage, failure reason, and next action.

get_document_result

Description: Fetch result content, Markdown output, artifacts, expiring download links, and missing artifact information for a completed job.

cancel_document_job

Description: Cancel a non-terminal document job.

delete_document_job

Description: Delete a terminal document job and reclaim related storage resources.

Parameter meanings:

• file_path
  A local file path on the MCP host machine. The MCP server reads this file and uploads it for you.

• file_id
  The ID of a file already uploaded to DocPurify. Use it with submit_document_for_processing.

• document_job_id
  Identifies the processing job. Save the value returned by upload or submit immediately, because later status, result, cancel, and delete calls all depend on it.

• processing_options
  Passes processing preferences. Omit it when you want to use the server defaults.

• status_filter
  Filters the job list. It is safer to inspect actual status values with list_document_jobs or get_document_job before adding a filter.

7.2 processing_options examples

Minimal local upload:

{
  "file_path": "/absolute/path/to/demo.pdf",
  "processing_options": {
    "selected_options": ["base_processing"]
  }
}

AI-enhanced document upload:

{
  "file_path": "/absolute/path/to/demo.pdf",
  "processing_options": {
    "selected_options": [
      "base_processing",
      "toc_validation",
      "image_validation",
      "content_validation"
    ],
    "language": "zh",
    "toc_pages": "2-3",
    "content_pages": "4-20",
    "toc_has_annotations": true
  }
}

Existing file_id with explicit page counts:

{
  "file_id": "file_123",
  "processing_options": {
    "selected_options": [
      "base_processing",
      "content_validation"
    ],
    "language": "en",
    "content_page_count": 18,
    "toc_page_count": 2
  }
}

Plain-text or Markdown file:

{
  "file_path": "/absolute/path/to/notes.md",
  "processing_options": {
    "selected_options": ["content_validation"],
    "language": "auto"
  }
}

Notes:

• Prefer selected_options as the main feature switch.
• text_validation and image_validation are compatibility booleans, but selected_options is the clearer long-term interface.
• For txt and md, prefer explicit content_validation.

7.3 Response shape

MCP tool calls return text content containing the JSON response from DocPurify.

Successful response:

{
  "success": true,
  "message": "ok",
  "data": {}
}

Business failures return isError: true to the MCP Host, with a machine-readable code in the content when available:

{
  "detail": {
    "code": "DOCUMENT_JOB_NOT_FOUND",
    "message": "document_job_id does not exist"
  }
}

8. Request examples

The natural-language instruction can be very short:

Please check my DocPurify workspace status first.

If you want the MCP host to upload a local file for you:

Upload the local file at /absolute/path/to/demo.pdf with DocPurify, then keep checking the job until the Markdown result is ready.

If you already have an uploaded file:

Submit the document with file_id file_123 for processing, check progress every 30 seconds, and fetch the Markdown result when it completes.

To inspect a result:

Check the processing status for document_job_id job_123. If it is complete, fetch the result and summarize the main content.

9. Key fields

Common get_workspace_overview fields:

• can_start_new_job
• active_jobs
• recent_jobs
• credit_balance
• storage_summary
• alerts
• recommended_next_actions

Common get_document_job fields:

• status
• progress
• current_stage
• failure_reason
• user_facing_explanation
• suggested_actions
• retryable
• result_ready

Common get_document_result fields:

• primary_markdown
• artifacts
• download_urls
• ttl_seconds
• missing_artifacts

10. Security and governance

DocPurify MCP calls are bound to the user behind the API key. The service checks resource ownership before accessing files or jobs.

Security recommendations:

• Do not place API keys in prompts, tool descriptions, screenshots, or shared docs.
• Do not treat download links as permanent URLs.
• Use separate accounts or test tenants for non-production integration work.
• Rotate or revoke keys when a device, script, or teammate no longer needs access.

11. Limits, pagination, and compatibility

Current limits:

• Remote Streamable HTTP MCP endpoint is not available yet.
• Resources and Prompts are not exposed.
• MCP does not upload local raw files directly.
• One account cannot keep multiple long-lived active MCP keys.

Pagination and filtering:

• list_document_jobs defaults to limit = 10.
• The maximum limit is 100.
• The current list endpoint does not return a cursor. Watch future versions for pagination fields.

Idempotency:

• get_workspace_overview, list_document_jobs, get_document_job, and get_document_result are read operations.
• upload_document_file, submit_document_for_processing, cancel_document_job, and delete_document_job change job state. Check current job state with get_document_job before retrying.
• External idempotency keys are not available in this release.

Compatibility:

• Adding a tool or adding response fields is treated as backward compatible.
• Removing a tool, renaming a field, or changing required parameters will be documented before release.
• Clients should ignore unknown response fields.

12. Errors and troubleshooting

For low-level connectivity checks outside an MCP Host, you can call the service debug path directly:

curl -X POST "https://api.docpurify.com/mcp/tools/get_workspace_overview" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $DOCPURIFY_MCP_KEY" \
  -d '{}'

13. Suggested strategy for AI agents

Use these rules in agent tool policies:

• Start each session with get_workspace_overview.
• Prefer upload_document_file when the user provides a local file path.
• Use submit_document_for_processing when the user already has a DocPurify file_id.
• Check current state before write operations to avoid duplicate submit, cancel, or delete calls.
• After receiving document_job_id, prefer polling get_document_job.
• Call get_document_result only when result_ready = true.
• If failure_reason exists, show it directly to the user.
• Confirm the job is completed, failed, or cancelled before deleting it.

14. FAQ

My client cannot see the tools. What should I check?

Confirm that the client loaded the docpurify MCP Server. Then check command, args, Node.js version, and environment variables. If the Server is visible but tools are missing, check the client's MCP logs.

Can I pass a local file path to submit_document_for_processing?

No. Use upload_document_file for local paths. submit_document_for_processing expects an existing DocPurify file_id.

Can download links be stored permanently?

No. Result download links expire. Read ttl_seconds, then call get_document_result again after expiry to get a fresh link.

When should I rotate an API Key?

Rotate or revoke it when the Key may be exposed, a device is retired, an integration is migrated, or a teammate no longer needs access.