com.debitura/mcp-server

Official14 tools

by debitura · TypeScript

Cross-border debt collection: submit and track cases handled by local partners in 183 countries.

Submit and track international debt collection cases across 183 countries.

Topics

accounts-receivableai-agentsanthropicclaudecursordebt-collectiondebt-recoveryfintechllmmcpmcp-servermodel-context-protocoltypescript

Captured live from the server via tools/list.

ping

Verify the connection to Debitura and show which creditor account the API key belongs to. Call this first to confirm the integration is set up correctly.

No parameters.

list_cases

List the creditor's debt collection cases with pagination, status filtering, and sorting. Returns compact case summaries: reference, debtor name + country, amounts, lifecycle, partner, key dates. Use get_case for full detail on a specific case. Lifecycle values (statuses filter and output): `PendingContractSigning` · `PendingVerificationInternal` · `PendingVerification` · `NeedsAdditionalDetails` · `Leads` · `LeadsQuoteGiven` · `Active` · `Paused` · `Closed` · `Merged` Sortable fields: `DateCreated` · `DateUpdated` · `DateFinished` · `DateCollectionStarted` · `DueDate` · `Date` · `GrossAmount` · `Remainder` · `InterestFees` · `CollectionFees` Sort format: `Field:asc` or `Field:desc`, e.g. `GrossAmount:desc` Note: results include the creditor's own test cases; the `isTestCase` flag on each case marks them.

Parameters (4)

pageinteger
Page number, starting from 1 (default 1)
pageSizeinteger
Results per page (default 10, max 100)
statusesarray
Filter by lifecycle status. Values: PendingContractSigning, PendingVerificationInternal, PendingVerification, NeedsAdditionalDetails, Leads, LeadsQuoteGiven, Active, Paused, Closed, Merged
sortstring
Sort expression: Field:asc or Field:desc. Valid fields: DateCreated, DateUpdated, DateFinished, DateCollectionStarted, DueDate, Date, GrossAmount, Remainder, InterestFees, CollectionFees. Example: GrossAmount:desc

get_case

Fetch one collection case in full detail. Look it up by Debitura case ID (GUID), by your own creditor reference (e.g. invoice number), or by the Debitura case reference shown in the portal. Provide exactly one of the three identifiers.

Parameters (3)

idstring
Debitura case ID (GUID)
creditorReferencestring
Your own reference for the case (e.g. invoice number)
caseReferencestring
Debitura case reference as shown in the portal

get_case_activity

Fetch the chronological timeline of a case — what has happened so far: status changes, partner actions, communications, and payments. Returns an envelope `{ items, currentEngagementPhase }`: `items` is the chronological event list, and `currentEngagementPhase` is the case's current engagement phase ("Pre-legal", "Legal", or "Enforcement"; null when no active engagement exists).

Parameters (1)

caseIdstringrequired
Debitura case ID (GUID)

get_case_messages

Read the chat conversation on a case between you and the collection partner handling it. Each message includes: senderName, role (Creditor / Partner / Managed by partner), sentAt (UTC), message. See the debitura://glossary/chat-roles resource for what each role means.

Parameters (1)

caseIdstringrequired
Debitura case ID (GUID)

get_case_payments

List every payment recorded on a case — money recovered so far.

Parameters (1)

caseIdstringrequired
Debitura case ID (GUID)

get_case_contract_status

Check which contracts (e.g. debt collection agreement, power of attorney) are signed or still blocking a case, including signing URLs for any outstanding documents.

Parameters (1)

caseIdstringrequired
Debitura case ID (GUID)

preview_case

Dry-run a collection case BEFORE creating it: returns eligibility, the assigned collection partner, pricing (success fee), and any contracts that would need signing. Nothing is persisted. ALWAYS call this before create_case and show the user the pricing and requirements.

Parameters (6)

amountToRecovernumberrequired
Total principal amount to recover
currencyCodestringrequired
ISO 4217 currency code, e.g. "EUR", "USD", "DKK"
debtorTypestringrequired
Company (B2B) or Private individual (B2C)
debtorCountryAlpha2stringrequired
Debtor country, ISO 3166-1 alpha-2, e.g. "DE", "US"
debtorStateAlpha2string
US state code, e.g. "CA" — REQUIRED when the debtor is in the United States
dueDatestring
Invoice due date (ISO 8601) — used to compute debt age for pricing

list_team_members

List the team members on the creditor's Debitura account. Use this to resolve a valid sender (userId or email) before calling send_case_message, or a case owner for create_case.

Parameters (2)

pageinteger
Page number (default 1)
pageSizeinteger
Results per page

list_case_files

List all documents attached to a case: file name, document type, description, upload date, and a time-limited SAS download URL. Each file also carries downloadUrlExpiresAt (UTC) — when the download URL stops working, so a cached URL can be refreshed in time. Use upload_case_file to attach new documents.

Parameters (1)

caseIdstringrequired
Debitura case ID (GUID)

get_account_summary

Return a count of cases per lifecycle stage for the creditor's account. Useful for a quick portfolio overview without listing all cases. Stages: PendingContractSigning, PendingVerificationInternal, PendingVerification, NeedsAdditionalDetails, Leads, LeadsQuoteGiven, Active, Paused, Closed, Merged. Note: these counts include the creditor's own test cases; list_cases exposes the `isTestCase` flag that marks them.

No parameters.

create_case

Submit a debt collection case to Debitura. This is a LEGAL AND FINANCIAL ACTION: a collection partner starts recovery against the debtor, and contractual fees apply on success. Required workflow — never skip it: 1. Call preview_case first and show the user the pricing, assigned partner, and any contracts that need signing. 2. Ask the user to explicitly confirm submission. 3. Only then call this tool. NEVER call it without the user's explicit confirmation in this conversation. Submission is idempotent: the server sends a unique Idempotency-Key and safely retries transient network failures without risk of duplicate cases. A 422 response is a business rejection — read its payload (it may contain signing URLs for required contracts, or duplicate-reference details).

Parameters (12)

amountToRecovernumberrequired
Total principal amount to recover
currencyCodestringrequired
ISO 4217 currency code, e.g. "EUR"
debtorobjectrequired
The debtor the claim is against
datestringrequired
Invoice date (ISO 8601, e.g. 2026-03-01) — required by the API
dueDatestringrequired
Invoice due date (ISO 8601, e.g. 2026-04-30). Required — Debitura computes the age of the debt from it, which affects pricing.
claimDescriptionstring
Description of the claim (what the debt is for)
commentsstring
Context for the collection partner, e.g. payment history or prior communication
creditorReferencestring
RECOMMENDED: your own reference (e.g. invoice number). Helps avoid business duplicates and lets you look the case up later.
assignedUserEmailstring
Email of the team member to own the case (use list_team_members to find valid team members)
allowPendingContractsboolean
Accept the case even if contracts (SDCA/POA) are unsigned — it waits in PendingContractSigning with signing URLs returned
isTestboolean
Create as test data (persisted but excluded from production metrics)
tagstring
Optional tag for grouping test data

upload_case_file

Attach a document to a case (invoice copy, contract, correspondence, proof of delivery). Max 25 MB. Allowed extensions: .pdf, .xls, .xlsx, .csv, .txt, .jpg, .jpeg, .png, .gif. Provide the file content base64-encoded.

Parameters (6)

caseIdstringrequired
Debitura case ID (GUID)
fileNamestringrequired
File name including extension, e.g. "invoice-1042.pdf"
contentBase64stringrequired
File content, base64-encoded
contentTypestring
MIME type, e.g. "application/pdf" (inferred from extension if omitted)
descriptionstring
Short description of the document
documentTypestring
Document category (default: OriginalInvoice). Values: OriginalInvoice · DebtorDocuments · CreditorDocuments · PartnerDocuments · DemandLetter · Miscellaneous

send_case_message

Send a chat message on a case to the collection partner handling it. The partner is notified by email. The message is attributed to a named team member, so a sender is REQUIRED: pass the sender's userId or email from list_team_members. Ask the user who the message should be sent as if it is not obvious.

Parameters (4)

caseIdstringrequired
Debitura case ID (GUID)
messagestringrequired
The message to send
senderUserIdstring
Team member ID sending the message (from list_team_members)
senderEmailstring
Team member email sending the message (alternative to senderUserId)

README.md9 KBView on GitHub

Debitura MCP Server

The MCP server for cross-border debt collection. Connect Claude, Cursor, VS Code, or any MCP-compatible agent to Debitura and manage international debt recovery from your AI assistant: check case status, read partner conversations, get pricing, and submit new collection cases — handled by vetted local collection partners in 183 countries on a no-cure-no-pay basis.

Endpoint: https://mcp.debitura.com/mcp (streamable HTTP)
Auth: your Debitura API key in the XApiKey header (or Authorization: Bearer <key>)
Get a key: log in at app.debitura.com → API key page
Connector page: debitura.com/integration/mcp-server

Tools

Read

Tool	What it does
`ping`	Test the connection — "✓ Connected as {your company}"
`list_cases`	List your collection cases (paging, status filter, sorting)
`get_case`	Fetch one case by ID, your own reference, or Debitura case reference
`get_case_activity`	Case timeline — what has happened so far (returns `{ items, currentEngagementPhase }`)
`get_case_messages`	Read the chat with the collection partner
`get_case_payments`	Money recovered on a case
`get_case_contract_status`	Which contracts are signed / blocking a case
`get_case_tasks`	Open tasks (action-items) for one case
`list_case_files`	List documents attached to a case, with time-limited download URLs
`get_account_summary`	Case counts per lifecycle stage — a quick portfolio overview
`list_tasks`	Every open task (action-item) across your account, with solutionUrl + resolving action
`preview_case`	Pricing + eligibility dry-run before submitting (nothing persisted)
`list_team_members`	Your team — used to attribute messages and assign case owners

Write

Tool	What it does
`create_case`	Submit a collection case. Safety-wrapped: preview first → explicit user confirmation → idempotent submit (auto `Idempotency-Key`, safe retries, no duplicate cases)
`upload_case_file`	Attach documents to a case (invoice copies, contracts — max 25 MB)
`send_case_message`	Message the collection partner on a case, attributed to a named team member

Every tool carries proper MCP annotations (readOnlyHint / destructiveHint), and create_case never auto-fires — it is a legal/financial action and always requires explicit human confirmation.

Distribution

Debitura runs this MCP server as a hosted service at https://mcp.debitura.com/mcp. That is the only supported way to use it — point any MCP client at the endpoint and authenticate with your Debitura API key (see Install below). There is no published npm package: the @debitura/mcp-server package is private ("private": true) and is not distributed on the npm registry. The source is published so you can audit it and, if you wish, run your own copy (see Self-hosting / development) — but normal usage is the hosted endpoint.

Install

Claude (web / desktop)

Settings → Connectors → Add custom connector → URL https://mcp.debitura.com/mcp. When asked for authentication, add your API key as the XApiKey header (or use the bearer-token field — both work).

Claude Code

bash

claude mcp add --transport http debitura https://mcp.debitura.com/mcp --header "XApiKey: YOUR_API_KEY"

Cursor

Add to ~/.cursor/mcp.json:

json

{
  "mcpServers": {
    "debitura": {
      "url": "https://mcp.debitura.com/mcp",
      "headers": { "XApiKey": "YOUR_API_KEY" }
    }
  }
}

VS Code (GitHub Copilot)

bash

code --add-mcp '{"name":"debitura","type":"http","url":"https://mcp.debitura.com/mcp","headers":{"XApiKey":"YOUR_API_KEY"}}'

Verify

Ask your assistant: "Ping Debitura" → you should see ✓ Connected as {your company}.

Example prompts

"What's the status of my Debitura cases? Anything that needs my attention?"
"What would it cost to collect a €12,000 B2B debt in Germany?"
"Any new messages from collection partners this week?"
"Submit a collection case against Acme GmbH in Berlin for invoice 2026-014, €8,400, due 1 March."

Security

Authentication & tenancy. The XApiKey header IS the tenant boundary. The server is stateless — each request creates a fresh MCP server bound to the caller's API key, which is passed straight through to the Debitura Customer API. No keys or case data are stored.
Rate limiting is handled at the Cloudflare edge (WAF / rate rules) that fronts mcp.debitura.com, not in-app. Note that some tools fan out to multiple Customer-API calls per invocation (e.g. get_account_summary queries one count per lifecycle stage), which the edge limits account for.
Vulnerability reports: see SECURITY.md.

Self-hosting / development

The supported way to use Debitura's MCP is the hosted endpoint above. The steps below are for local development / auditing of this repository only.

bash

npm install
npm run dev          # starts on :3000, POST /mcp

Env var	Default	Purpose
`PORT`	`3000`	Listen port
`DEBITURA_API_BASE_URL`	`https://customer-api.debitura.com`	Point at `https://testcustomer-api.debitura.com` for the test environment

See .env.example for a starter env file.

bash

npm run build && npm start        # production-style local run
docker build -t debitura-mcp . && docker run -p 3000:3000 debitura-mcp

Deployment note: the hosted service deploys the built app as a zip to Azure App Service (see .github/workflows/deploy.yml) — it does not run the Docker image in production. The Dockerfile is provided for local/self-hosted use.

E2E tests

Runs every tool against the test environment (creates only tagged isTest cases and deletes them):

bash

DEBITURA_API_BASE_URL=https://testcustomer-api.debitura.com npm run dev   # terminal 1
DEBITURA_TEST_API_KEY=<test key> MCP_URL=http://localhost:3000/mcp npx tsx scripts/e2e.ts

Regenerating API types

Types and the HTTP client are generated from the Customer API's OpenAPI spec (openapi/customer-api.json) via openapi-typescript — the curated 16-tool layer on top is hand-written:

bash

npm run fetch:spec   # pull latest spec + regenerate src/generated/customer-api.d.ts

Releasing a new version

The version lives in package.json (config.ts and client.ts derive from it). When bumping it, also update server.json — its version field is independent and must match the published registry listing. (smithery.yaml has no version field; Smithery picks up the package version automatically.)

When adding or removing a tool, also update the tool catalog above and the tools/list assertion in scripts/e2e.ts (it asserts the exact registered tool set).

About Debitura

Debitura is a global debt collection platform covering 183 countries. Creditors submit overdue B2B and B2C claims; vetted local collection partners in the debtor's jurisdiction recover them, typically no-cure-no-pay. Learn more at debitura.com · API docs at docs.debitura.com.

Install

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.debitura.com/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.