{
  "markdown": "# Debitura MCP Server\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-1f6feb.svg)](./LICENSE)\n[![Model Context Protocol](https://img.shields.io/badge/MCP-Streamable_HTTP-000000.svg)](https://modelcontextprotocol.io)\n[![Node](https://img.shields.io/badge/Node-%E2%89%A520-339933.svg?logo=node.js&logoColor=white)](https://nodejs.org)\n[![Docs](https://img.shields.io/badge/Docs-docs.debitura.com-0b7285.svg)](https://docs.debitura.com)\n\n**The MCP server for cross-border debt collection.** Connect Claude, Cursor, VS Code, or any\nMCP-compatible agent to [Debitura](https://www.debitura.com) and manage international debt\nrecovery from your AI assistant: check case status, read partner conversations, get pricing,\nand submit new collection cases — handled by vetted local collection partners in 183 countries\non a no-cure-no-pay basis.\n\n- **Endpoint:** `https://mcp.debitura.com/mcp` (streamable HTTP)\n- **Auth:** your Debitura API key in the `XApiKey` header (or `Authorization: Bearer <key>`)\n- **Get a key:** log in at [app.debitura.com](https://app.debitura.com) → [API key page](https://app.debitura.com/CreditorApiKey)\n- **Connector page:** [debitura.com/integration/mcp-server](https://www.debitura.com/integration/mcp-server)\n\n## Tools\n\n### Read\n\n| Tool                       | What it does                                                                           |\n| -------------------------- | -------------------------------------------------------------------------------------- |\n| `ping`                     | Test the connection — \"✓ Connected as {your company}\"                                  |\n| `list_cases`               | List your collection cases (paging, status filter, sorting)                            |\n| `get_case`                 | Fetch one case by ID, your own reference, or Debitura case reference                   |\n| `get_case_activity`        | Case timeline — what has happened so far (returns `{ items, currentEngagementPhase }`) |\n| `get_case_messages`        | Read the chat with the collection partner                                              |\n| `get_case_payments`        | Money recovered on a case                                                              |\n| `get_case_contract_status` | Which contracts are signed / blocking a case                                           |\n| `get_case_tasks`           | Open tasks (action-items) for one case                                                 |\n| `list_case_files`          | List documents attached to a case, with time-limited download URLs                     |\n| `get_account_summary`      | Case counts per lifecycle stage — a quick portfolio overview                           |\n| `list_tasks`               | Every open task (action-item) across your account, with solutionUrl + resolving action |\n| `preview_case`             | Pricing + eligibility dry-run before submitting (nothing persisted)                    |\n| `list_team_members`        | Your team — used to attribute messages and assign case owners                          |\n\n### Write\n\n| Tool                | What it does                                                                                                                                                        |\n| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `create_case`       | Submit a collection case. Safety-wrapped: preview first → explicit user confirmation → idempotent submit (auto `Idempotency-Key`, safe retries, no duplicate cases) |\n| `upload_case_file`  | Attach documents to a case (invoice copies, contracts — max 25 MB)                                                                                                  |\n| `send_case_message` | Message the collection partner on a case, attributed to a named team member                                                                                         |\n\nEvery tool carries proper MCP annotations (`readOnlyHint` / `destructiveHint`), and `create_case`\nnever auto-fires — it is a legal/financial action and always requires explicit human confirmation.\n\n## Distribution\n\nDebitura runs this MCP server as a **hosted service** at `https://mcp.debitura.com/mcp`. That is the\nonly supported way to use it — point any MCP client at the endpoint and authenticate with your\nDebitura API key (see [Install](#install) below). There is **no published npm package**: the\n`@debitura/mcp-server` package is private (`\"private\": true`) and is not distributed on the npm\nregistry. The source is published so you can audit it and, if you wish, run your own copy (see\n[Self-hosting / development](#self-hosting--development)) — but normal usage is the hosted endpoint.\n\n## Install\n\n### Claude (web / desktop)\n\nSettings → Connectors → **Add custom connector** → URL `https://mcp.debitura.com/mcp`.\n\nAnthropic is rolling out a **Request headers** option in that same dialog that lets you\nauthenticate without OAuth — but it's a gated beta (Anthropic: \"contact us for early\naccess\"), so most accounts won't see it yet. If you do see it, add header `x-api-key`\nwith your Debitura API key as the value. If you don't, use Claude Code or the Claude\nDesktop config-file method below instead — both work today regardless of beta access.\n\n### Claude Code\n\n```bash\nclaude mcp add --transport http debitura https://mcp.debitura.com/mcp --header \"XApiKey: YOUR_API_KEY\"\n```\n\n### Claude Desktop (no beta access to Request headers)\n\nBypass the Connectors UI entirely by editing `claude_desktop_config.json` directly — a\nseparate mechanism from the web-synced Connectors UI, no OAuth involved — using the\n[`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge:\n\n```json\n{\n  \"mcpServers\": {\n    \"debitura\": {\n      \"command\": \"npx\",\n      \"args\": [\"mcp-remote\", \"https://mcp.debitura.com/mcp\", \"--header\", \"XApiKey:${DEBITURA_KEY}\"],\n      \"env\": { \"DEBITURA_KEY\": \"YOUR_API_KEY\" }\n    }\n  }\n}\n```\n\nFile location: macOS `~/Library/Application Support/Claude/claude_desktop_config.json`,\nWindows `%APPDATA%\\Claude\\claude_desktop_config.json`. Restart Claude Desktop after\nsaving — the server appears under Settings → Connectors → Manage connectors, even\nthough you never touched \"Add custom connector\".\n\n### Cursor\n\nAdd to `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"debitura\": {\n      \"url\": \"https://mcp.debitura.com/mcp\",\n      \"headers\": { \"XApiKey\": \"YOUR_API_KEY\" }\n    }\n  }\n}\n```\n\n### VS Code (GitHub Copilot)\n\n```bash\ncode --add-mcp '{\"name\":\"debitura\",\"type\":\"http\",\"url\":\"https://mcp.debitura.com/mcp\",\"headers\":{\"XApiKey\":\"YOUR_API_KEY\"}}'\n```\n\n### Verify\n\nAsk your assistant: _\"Ping Debitura\"_ → you should see `✓ Connected as {your company}`.\n\n## Example prompts\n\n- _\"What's the status of my Debitura cases? Anything that needs my attention?\"_\n- _\"What would it cost to collect a €12,000 B2B debt in Germany?\"_\n- _\"Any new messages from collection partners this week?\"_\n- _\"Submit a collection case against Acme GmbH in Berlin for invoice 2026-014, €8,400, due 1 March.\"_\n\n## Security\n\n- **Authentication & tenancy.** The `XApiKey` header IS the tenant boundary. The server is\n  **stateless** — each request creates a fresh MCP server bound to the caller's API key, which is\n  passed straight through to the Debitura Customer API. No keys or case data are stored.\n- **Rate limiting** is handled at the **Cloudflare edge** (WAF / rate rules) that fronts\n  `mcp.debitura.com`, not in-app. Note that some tools fan out to multiple Customer-API calls per\n  invocation (e.g. `get_account_summary` queries one count per lifecycle stage), which the edge\n  limits account for.\n- **Vulnerability reports:** see [SECURITY.md](./SECURITY.md).\n\n## Self-hosting / development\n\nThe supported way to use Debitura's MCP is the hosted endpoint above. The steps below are for\n**local development / auditing** of this repository only.\n\n```bash\nnpm install\nnpm run dev          # starts on :3000, POST /mcp\n```\n\n| Env var                 | Default                             | Purpose                                                                   |\n| ----------------------- | ----------------------------------- | ------------------------------------------------------------------------- |\n| `PORT`                  | `3000`                              | Listen port                                                               |\n| `DEBITURA_API_BASE_URL` | `https://customer-api.debitura.com` | Point at `https://testcustomer-api.debitura.com` for the test environment |\n\nSee [`.env.example`](./.env.example) for a starter env file.\n\n```bash\nnpm run build && npm start        # production-style local run\ndocker build -t debitura-mcp . && docker run -p 3000:3000 debitura-mcp\n```\n\n> **Deployment note:** the hosted service deploys the built app as a **zip to Azure App Service**\n> (see `.github/workflows/deploy.yml`) — it does **not** run the Docker image in production. The\n> `Dockerfile` is provided for local/self-hosted use.\n\n### E2E tests\n\nRuns every tool against the test environment (creates only tagged `isTest` cases and deletes them):\n\n```bash\nDEBITURA_API_BASE_URL=https://testcustomer-api.debitura.com npm run dev   # terminal 1\nDEBITURA_TEST_API_KEY=<test key> MCP_URL=http://localhost:3000/mcp npx tsx scripts/e2e.ts\n```\n\n### Regenerating API types\n\nTypes and the HTTP client are generated from the Customer API's OpenAPI spec\n(`openapi/customer-api.json`) via `openapi-typescript` — the curated 16-tool layer on top is\nhand-written:\n\n```bash\nnpm run fetch:spec   # pull latest spec + regenerate src/generated/customer-api.d.ts\n```\n\n### Releasing a new version\n\nThe version lives in **`package.json`** (`config.ts` and `client.ts` derive from it). When bumping\nit, also update **`server.json`** — its `version` field is independent and must match the published\nregistry listing. (`smithery.yaml` has no version field; Smithery picks up the package version\nautomatically.)\n\nWhen **adding or removing a tool**, also update the tool catalog above and the `tools/list`\nassertion in `scripts/e2e.ts` (it asserts the exact registered tool set).\n\n## About Debitura\n\nDebitura is a global debt collection platform covering 183 countries. Creditors submit overdue\nB2B and B2C claims; vetted local collection partners in the debtor's jurisdiction recover them,\ntypically no-cure-no-pay. Learn more at [debitura.com](https://www.debitura.com) · API docs at\n[docs.debitura.com](https://docs.debitura.com).\n",
  "bytes": 10568,
  "sha": "6d758418bcff88d67c9a8f4d0e314cfb106642551d97314872f18321c432b88c",
  "repo_slug": "debitura/debitura.mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_debitura_mcp_server_162f0fb3/readme"
}