Introdução

O servidor MCP da Régua de Cobrança é um servidor Model Context Protocol remoto que expõe as operações da API pública — devedores, cobranças, réguas, modelos de mensagem, notificações, acordos, disputas, negativações, protestos, tarefas, importações, exportações, webhooks e métricas de recuperação — como tools que um cliente de IA pode chamar. Você o conecta por URL; não há nada para instalar.

Ele é servido em host próprio, mcp.dunning.kobana.com.br, com transporte Streamable HTTP em modo stateless e autenticação por Bearer token. Nenhum certificado de cliente está envolvido.

:::info Disponibilidade O servidor e suas 118 tools estão prontos, e a autenticação é pelo authorization server da Kobana, que já registra o recurso MCP da Régua de Cobrança e os seus escopos: pelo fluxo OAuth 2.1, em que o cliente recebe só a URL e faz o login sozinho, ou por um token pessoal criado na sua conta Kobana. A borda dedicada (distribution mcp.dunning.*, WAF e DNS) ainda está sendo provisionada. :::

Quando usar

	API REST (/v1)	Servidor MCP (este)
Consumidor	seu backend	um cliente de IA (Claude, ChatGPT, uma IDE)
Configuração	token, fora de banda	uma URL
Transporte	HTTPS/REST	Streamable HTTP (JSON-RPC 2.0)
Autenticação	Bearer token emitido para a API	OAuth 2.1 ou token pessoal, sempre emitido para o MCP
Autoridade	a da integração	as permissões de dashboard da pessoa dona do token
Superfície	as operações publicadas da /v1	118 tools, uma por operação publicada

O servidor MCP não substitui a API REST. Cada tool despacha in-process para o handler da /v1 que implementa a operação, então filtros, validação, regras de negócio e isolamento por organização são exatamente os mesmos. Se você está escrevendo código, use a API REST. Se está conectando um assistente, use isto.

O princípio

Uma capability só existe no MCP se existir na API pública.

Não há uma segunda implementação de nada. A tool chama o handler do endpoint com a identidade que o token do chamador já provou — a mesma pessoa, a mesma organização —, então ele roda como rodaria para qualquer requisição HTTP, e a auditoria que grava fica atribuída ao token. Uma tool faz o que o endpoint faz por REST — nunca mais.

A consequência prática: o que hoje só existe no dashboard não vira tool antes de virar endpoint. Recursos administrativos (membros, papéis, chaves, configurações) não têm tool nenhuma.

Os nomes das tools

Toda tool segue o padrão dunning_<recurso>_<verbo>: dunning_charges_list, dunning_charges_notify, dunning_agreements_accept. Os argumentos são um objeto plano em snake_case — parâmetros de caminho (id, cp_id, step_id, delivery_id), query e corpo lado a lado.

Uma tool não pertence a recurso nenhum: dunning_me devolve a identidade da conexão — a pessoa, a organização, os escopos e a expiração do token — e responde a qualquer token válido. É a primeira a chamar quando a pergunta é "qual organização estou usando?".

O que você vê é mais estreito que o catálogo

tools/list devolve apenas as tools que este chamador pode rodar, filtradas por duas coisas que só subtraem: o escopo do token e as permissões de dashboard da pessoa dona do token naquela organização. Um agente não é informado de capacidades que só levariam negativa. As regras estão em Autenticação.

Primeiros passos

1. Aponte seu cliente para a URL do servidor — veja Endpoints e Clientes.

2. Autorize. O cliente abre o login da Kobana; entre com uma conta da organização e autorize o acesso. Se você nunca entrou no dashboard da Régua de Cobrança com a sua conta Kobana, entre uma vez antes — veja Permissões da pessoa.

3. Liste as tools para confirmar o que o seu acesso alcança — peça ao assistente, ou, com um token emitido para o MCP em mãos:

   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 a documentação — o catálogo completo está em Tools.

Próximos passos

• Autenticação — o fluxo OAuth, o token pessoal, as permissões da pessoa, o escopo do token e os modos de falha.
• Endpoints — URLs por ambiente e rotas servidas.
• Transporte — JSON-RPC, as duas eras do protocolo, cabeçalhos e métodos.
• Resources e prompts — documentos por URI, roteiros prontos, autocomplete e a confirmação de tools destrutivas.
• Clientes — como conectar Claude Code e clientes por arquivo.
• Listagem e paginação — page, per_page, sort_by, include e filtros.
• Erros — os dois canais de falha, e por que a distinção importa.
• Limite de requisições — os baldes por pessoa e organização.
• Idempotência — idempotency_key nas escritas.
• Tools — o catálogo das 118 tools.