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
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
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

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

Cursor

Add to ~/.cursor/mcp.json:

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

VS Code (GitHub Copilot)

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.

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.

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):

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 14-tool layer on top is hand-written:

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.