Developer Tools

MCP Server

Let AI agents compare documents through Differino. Works with Claude, Cursor, and any MCP-compatible client.

What is MCP?

The Model Context Protocol is a standard for AI agents to use external tools. Differino's MCP server lets agents upload and compare documents programmatically, no browser needed. Your AI assistant can compare contracts, review document changes, and summarize differences on its own.

Quick Start

Install

bash

npx -y differino-mcp
# or, with a global install:
npm install -g differino-mcp

Configure Claude Desktop

Generate an API key at Settings → API Key, then add to your claude_desktop_config.json:

json

{
  "mcpServers": {
    "differino": {
      "command": "npx",
      "args": ["-y", "differino-mcp"],
      "env": {
        "DIFFERINO_API_KEY": "dfn_your_api_key_here"
      }
    }
  }
}

Set environment variables

Variable	Required	Description
DIFFERINO_API_KEY	Yes	Your API key. Generate one at Settings → API Key
DIFFERINO_URL	No	Base URL (default: https://www.differino.com)

Available Tools

compare_documents

Upload two local files and get fast text or grouped visual comparison metadata. Files up to 45 MB each; large files go through signed upload URLs automatically. If the response is status processing, poll get_comparison until it is ready.

file_a_pathrequiredAbsolute path to first document

file_b_pathrequiredAbsolute path to second document

comparison_modeoptionalvisual or text

get_comparison

Check status, text summary, and visual artifact results. Also used to poll comparisons that are still processing.

comparison_idrequiredThe comparison UUID

list_comparisons

List recent comparisons in your workspace, newest first, with status, mode, file names, and summary counters.

limitoptional1 to 50, default 10

statusoptionalpending, processing, ready, or failed

export_comparison_pdf

Export a finished comparison as a PDF report and get a temporary download URL. Waits for the export by default.

comparison_idrequiredThe comparison UUID

include_unchangedoptionalInclude unchanged content, default false

localeoptionalen, es, zh, fr, de, or hi

waitoptionalPoll until the export completes, default true

summarize_visual_diff

Compact page-by-page change summary from the visual manifest, deduplicated by groupId, without image URLs or pixel boxes.

comparison_idrequiredThe comparison UUID

min_salienceoptionaltechnical, subtle, visible, or structural

include_snippetsoptionalInclude text snippets, default true

max_changes_per_pageoptionalCap per page, default 20

get_text_diff

Fetch the block-level text diff with word-level spans for modified blocks. Best for quoting exact text changes.

comparison_idrequiredThe comparison UUID

only_changedoptionalSkip equal blocks, default true

max_blocksoptionalMaximum blocks returned, default 100

get_balance

Check your credit balance, remaining free comparison, and plan. Useful before comparing or after a NO_CREDITS error.

No parameters

Response Contract

Comparison responses include a text summary and, when available, visual artifact metadata for page renders and highlighted regions. Large documents can outlast the initial wait: the response then has status: processing and you should poll get_comparison (or GET /api/v1/comparisons/{id}) until status is ready.

visual.statusOne of ready, pending, missing, or disabled.

visual.manifestPage image URLs, red/green highlighted regions, grouped change identities, and salience metadata when visual.status is ready.

regions[].groupIdStable identity for paired fragments, including modifications that cross page boundaries.

regions[].salienceIndicates subtle, visible, structural, or technical changes so clients can surface hard-to-see differences.

visual.diffUrlSigned URL for the visual diff JSON when available.

visualManifestDeprecated top-level duplicate of visual.manifest; read visual.manifest. It will be removed in a future version.

export statusExport jobs report pending, processing, completed (with downloadUrl), or failed. Poll until completed.

If visual.status is not ready, use the text diff summary and full comparison URL instead of treating the visual result as no changes.

Supported Formats

PDF

DOCX

TXT

REST API

You can also use the API directly. Authenticate with your API key via the Authorization header.

Compare two small files (multipart, up to ~4.5 MB total)

bash

curl -X POST https://www.differino.com/api/v1/compare \
  -H "Authorization: Bearer dfn_your_api_key" \
  -H "Idempotency-Key: my-unique-key-001" \
  -F "file_a=@original.pdf" \
  -F "file_b=@modified.pdf" \
  -F "comparison_mode=visual" \
  -F "accuracy_mode=balanced"

accuracy_mode is optional: fast, balanced, or thorough. Defaults to balanced for visual comparisons and fast for text comparisons. Idempotency-Key is optional: repeating a key returns the existing comparison without charging again. The same key with different files, versions, mode or accuracy is rejected with 422 IDEMPOTENCY_KEY_REUSED. Keys never expire.

Larger files: signed upload flow (up to 45 MB each)

bash

# 1. Declare both files, get signed upload URLs + version ids
curl -X POST https://www.differino.com/api/v1/uploads \
  -H "Authorization: Bearer dfn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"fileA": {"name": "original.pdf", "type": "application/pdf", "size": 10485760},
       "fileB": {"name": "modified.pdf", "type": "application/pdf", "size": 11534336}}'

# 2. PUT each file body to its uploadUrl (valid for 2 hours)
curl -X PUT "{fileA.uploadUrl}" \
  -H "Content-Type: application/pdf" \
  --data-binary @original.pdf

# 3. Verify the stored objects and queue extraction
curl -X POST https://www.differino.com/api/v1/uploads/complete \
  -H "Authorization: Bearer dfn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"versionIds": ["{fileA.versionId}", "{fileB.versionId}"]}'

# 4. Compare the uploaded versions (JSON body, consumes the credit)
curl -X POST https://www.differino.com/api/v1/compare \
  -H "Authorization: Bearer dfn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"versionAId": "{fileA.versionId}", "versionBId": "{fileB.versionId}", "comparisonMode": "visual"}'

Multipart requests over ~4.5 MB total return 413 PAYLOAD_TOO_LARGE (Vercel request body limit). Steps 1 to 3 are free; only step 4 consumes the free comparison or a credit. The MCP server switches to this flow automatically.

Check comparison status

bash

curl https://www.differino.com/api/v1/comparisons/{id} \
  -H "Authorization: Bearer dfn_your_api_key"

Account status: credits, free comparison, plan

bash

curl https://www.differino.com/api/v1/me \
  -H "Authorization: Bearer dfn_your_api_key"

Rate Limits

Endpoint	Limit per workspace
POST /api/v1/compare	10 / minute
POST /api/v1/comparisons/:id/export	20 / hour, max 5 queued jobs
GET endpoints (list, get, status, me)	120 / minute, shared
POST /api/v1/uploads + /uploads/complete	30 / minute, shared

Exceeding a limit returns HTTP 429 with code RATE_LIMITED, a retryAfter field in seconds, and a Retry-After header.

Error Codes

HTTP	Code	Meaning
400	INVALID_REQUEST	Malformed body or parameters (bad JSON, missing fields, invalid UUIDs or limits)
400	INVALID_FILE	Unsupported type, content does not match its extension, or upload verification failed
400	FILE_TOO_LARGE	Declared size exceeds the 45 MB per-file limit
400	VERSION_FAILED / VERSION_NOT_PENDING / VERSION_NOT_COMPLETED	Referenced version failed, was already completed, or its upload was never completed (call /uploads/complete)
401	UNAUTHORIZED	Missing or invalid API key
402	NO_CREDITS	No free comparison and no credits left; response includes buyUrl
404	NOT_FOUND	Comparison or export job not found in your workspace
404	VERSION_NOT_FOUND	Version not found in your workspace
413	PAYLOAD_TOO_LARGE	Multipart body over ~4.5 MB total; use the signed upload flow
422	IDEMPOTENCY_KEY_REUSED	Same Idempotency-Key sent with different files, versions, mode or accuracy
429	RATE_LIMITED	Rate limit exceeded; retry after retryAfter seconds
429	EXPORT_QUEUE_FULL	More than 5 export jobs pending or processing in your workspace
500	INTERNAL_ERROR / EXTRACTION_FAILED / COMPARISON_FAILED	Server-side failure; metering is refunded when a comparison fails before completing
504	EXTRACTION_TIMEOUT	Text extraction did not finish within the request window; metering refunded

Credits

Every account gets 1 free comparison. After that, comparisons use credits from your balance. Credit packs start at €1.99 for 10 comparisons.

View Pricing