Connect DocuClipper to AI Agents (MCP)

DocuClipper exposes its extraction tools to AI agents through a set of Model Context Protocol (MCP) style tool endpoints. An agent can discover the available tools, call them, and get structured transactions back — no manual uploading.

What's shipped today: the MCP tools are served as a PAT-authenticated JSON-over-HTTP adapter under /api/v1/agent/mcp. This is a lightweight tool-dispatch surface, not a full Streamable-HTTP MCP server, and there is no standalone npx package to drop into Claude Desktop or Cursor yet. If your agent runtime can call HTTP tools (most can), use the endpoints below. A plug-and-play stdio client is on the roadmap.

Prerequisites

• A DocuClipper account with a Personal Access Token. Get yours at Settings → API & Webhooks (/account?section=api). See API Access: Personal Access Tokens.
• A client that can send authenticated HTTP requests (an agent framework, a script, or your own code).

All requests use the base URL https://www.docuclipper.com/api/v1/agent/mcp and the header Authorization: Bearer <PAT> (PATs start with dcp_).

Discover the tools

The tool registry is discoverable at runtime, so your agent always gets the current set:

TOKEN="dcp_xxxxxxxx"
BASE="https://www.docuclipper.com/api/v1/agent/mcp"

# List all tools (name, description, JSON input schema).
curl -sS "$BASE/tools" -H "Authorization: Bearer $TOKEN"

# Get the schema for one tool.
curl -sS "$BASE/tools/convert_bank_statement/schema" -H "Authorization: Bearer $TOKEN"

Call a tool

POST to /tools/<name> with the tool's parameters as a JSON body:

# One-shot: upload a base64 PDF, extract, poll, and return transactions.
curl -sS -X POST "$BASE/tools/convert_bank_statement" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"filename\":\"statement.pdf\",\"filebase64\":\"$(base64 -i statement.pdf)\",\"format\":\"csv\"}"

The response is { "result": ... }, where result is the tool's output.

Available tools

Tool	What it does
convert_bank_statement	One-shot: accepts a base64 PDF, uploads it, extracts, polls until done, and returns transactions (JSON or CSV). Best for files under ~10 MB.
upload_url	Gets a presigned S3 URL for uploading large files directly. Returns a document id.
convert_document	Enqueues an extraction job for one or more documents you already uploaded.
get_job_status	Polls a job by id and returns its status and transaction count.
download_transactions	Fetches transactions from any completed job by id (up to 10,000 rows), as JSON or CSV.
get_transactions	Alias of download_transactions.

For large files (over ~10 MB) use the async path instead of convert_bank_statement: upload_url → PUT the bytes to S3 → convert_document → get_job_status → download_transactions.

Timeouts

convert_bank_statement blocks until the job finishes or its timeout expires (default 300 seconds). For long jobs, pass a larger timeoutSeconds (for example 600) or switch to the async path above.

Troubleshooting

HTTP 401: the PAT is missing, invalid, expired, or was revoked. Send it as Authorization: Bearer dcp_... and generate a new one at Settings → API & Webhooks if needed.

HTTP 402 / out of pages: your account is out of pages. Top up at Settings → Plan & Billing.

404 "Tool not found": the tool name is misspelled or not in the registry. Call GET /tools to see the exact names.

A tool call returns 500: the underlying extraction failed. Check the job with get_job_status, and see API: common recipes for the equivalent raw endpoints and error shapes.

Related

• MCP integration overview — supported clients and use cases
• API Access: Personal Access Tokens
• API: common recipes
• Webhooks overview
• API reference