Debitura MCP Server

![License: MIT](./LICENSE) ![Model Context Protocol](https://modelcontextprotocol.io) ![Node](https://nodejs.org) ![Docs](https://docs.debitura.com)

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.

Anthropic is rolling out a Request headers option in that same dialog that lets you authenticate without OAuth — but it's a gated beta (Anthropic: "contact us for early access"), so most accounts won't see it yet. If you do see it, add header x-api-key with your Debitura API key as the value. If you don't, use Claude Code or the Claude Desktop config-file method below instead — both work today regardless of beta access.

Claude Code

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

Claude Desktop (no beta access to Request headers)

Bypass the Connectors UI entirely by editing claude_desktop_config.json directly — a separate mechanism from the web-synced Connectors UI, no OAuth involved — using the mcp-remote bridge:

{
  "mcpServers": {
    "debitura": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.debitura.com/mcp", "--header", "XApiKey:${DEBITURA_KEY}"],
      "env": { "DEBITURA_KEY": "YOUR_API_KEY" }
    }
  }
}

File location: macOS ~/Library/Application Support/Claude/claude_desktop_config.json, Windows %APPDATA%\Claude\claude_desktop_config.json. Restart Claude Desktop after saving — the server appears under Settings → Connectors → Manage connectors, even though you never touched "Add custom connector".

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

Debitura.MCP