mcp-server

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

Write

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

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.