Skip to main content

Introduction

The Régua de Cobrança MCP server is a remote Model Context Protocol server for Régua de Cobrança (Kobana's dunning product). It exposes the operations of the public API — debtors, charges, collection rules, notifications, agreements, disputes, credit-bureau reports, protests and recovery metrics — as tools an AI client can call. You connect it by URL; there is nothing to install.

It is served on its own host, mcp.dunning.kobana.com.br, with Streamable HTTP transport in stateless mode and Bearer token authentication. No client certificate is involved.

:::info Availability The server and its 118 tools are ready, and authentication goes through the Kobana authorization server — which already registers the Régua de Cobrança MCP resource and its dunning/* scopes: via the OAuth 2.1 flow, where the client is given only the URL and signs in on its own, or via a personal token created in your Kobana account. The dedicated edge (the mcp.dunning.* distribution, WAF and DNS) is still being provisioned. :::

When to use it​

REST API (/v1)MCP server (this)
Consumeryour backendan AI client (Claude, ChatGPT, an IDE)
Setupa token, out of bandone URL
TransportHTTPS/RESTStreamable HTTP (JSON-RPC 2.0)
AuthBearer token issued for the APIOAuth 2.1 or a personal token, always issued for MCP
Acts withthe integration's authoritythe permissions of the person who owns the token
Surfacethe published /v1 operations118 tools, one per published operation

The MCP server does not replace the REST API. Every tool dispatches in-process to the /v1 handler that implements the operation, so filters, validation, business rules and organization isolation are exactly the same. If you are writing code, use the REST API. If you are connecting an assistant, use this.

The principle​

A capability exists in MCP only if it exists in the public API.

There is no second implementation of anything. The tool calls the endpoint's handler with the identity the caller's token already proved — the same person, the same organization — so it runs the way it would for any HTTP request, and the audit trail it writes is attributed to that token. A tool does what the endpoint does over REST — never more.

The practical consequence: what exists only in the dashboard today does not become a tool before it becomes an endpoint. Tools are named dunning_<resource>_<verb> — dunning_charges_list, dunning_charges_notify, dunning_agreements_accept.

What you see is narrower than the catalogue​

tools/list returns only the tools this caller can actually run, filtered twice: by the token's scope and by the dashboard permissions of the person who owns the token. An agent is not told about capabilities that would only earn it a refusal. The rules are in Authentication.

Getting started​

  1. Point your client at the server URL — see Endpoints and Clients.

  2. Authorize. The client opens the Kobana sign-in; sign in with an account that is a member of the organization and authorize access. Or create a personal token for the MCP usage. See Authentication.

  3. Check who you are and what you reach. Ask the assistant "which organization am I using in Régua de Cobrança?" — it calls dunning_me. Or, with a token issued for MCP at hand, list the tools:

    curl https://mcp.dunning.kobana.com.br/ \
      -H "Authorization: Bearer $MCP_TOKEN" \
      -H "Content-Type: application/json" \
      -H "Accept: application/json" \
      -H "MCP-Protocol-Version: 2025-06-18" \
      -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

  4. Explore the documentation — the full catalogue is in Tools.

Next steps​

  • Authentication — the OAuth flow, the personal token, the person's permissions, the token scope and the failure modes.
  • Endpoints — URLs per environment and the routes served.
  • Transport — JSON-RPC, protocol versions, headers and methods.
  • Resources and prompts — documents by URI, ready-made prompts, autocomplete, and the confirmation of destructive tools.
  • Clients — connecting Claude Code, file-configured clients, Claude and ChatGPT.
  • Listing and pagination — page, per_page, sort_by, include and named filters.
  • Errors — the two failure channels, and why the difference matters.
  • Rate limit and Idempotency.
  • Tools — the catalogue of all 118 tools.