com.debitura/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 MCP annotations (readOnlyHint / destructiveHint); the write tools are marked destructive. create_case is a legal/financial action: its tool description tells the assistant to run preview_case and get the user's explicit confirmation before submitting. Whether your MCP client also asks before running a tool depends on the client and its settings.

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.
• Transport. The hosted endpoint is served over HTTPS through Cloudflare.
• Rate limits. Tool calls are forwarded to the Debitura Customer API, so the Customer API's rate limits apply to your API key. Some tools make several Customer API calls per invocation (e.g. get_account_summary queries one count per lifecycle stage), and each call counts.
• 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.