Saltar al contenido principal

Introducción

El servidor MCP de Régua de Cobrança es un servidor Model Context Protocol remoto que expone las operaciones de la API pública — deudores y sus contactos, cobros, reglas de cobranza y sus pasos, plantillas, notificaciones, tareas, interacciones, acuerdos y campañas de negociación, disputas, negativaciones y protestos, importaciones y exportaciones, webhooks, auditoría y métricas de recuperación — como tools que un cliente de IA puede llamar. Lo conectas por URL; no hay nada que instalar.

Se sirve en host propio, mcp.dunning.kobana.com.br, con transporte Streamable HTTP en modo stateless y autenticación por Bearer token. No hay certificado de cliente involucrado.

:::info Disponibilidad El servidor y sus 118 tools están listos, y la autenticación pasa por el authorization server de Kobana, que ya registra el recurso MCP de Régua de Cobrança y sus scopes: por el flujo OAuth 2.1, en el que el cliente recibe solo la URL e inicia sesión por su cuenta, o por un token personal creado en tu cuenta Kobana. El borde dedicado (distribución mcp.dunning.*, WAF y DNS) aún se está aprovisionando. :::

Cuándo usarlo​

API REST (/v1)Servidor MCP (este)
Consumidortu backendun cliente de IA (Claude, ChatGPT, un IDE)
Configuraciónun token, fuera de bandauna URL
TransporteHTTPS/RESTStreamable HTTP (JSON-RPC 2.0)
AutenticaciónBearer token emitido para la APIOAuth 2.1 o token personal, siempre emitido para el MCP
Con la autoridad dela integración (los permisos de la clave)la persona dueña del token (sus permisos en el panel)
Superficielas operaciones publicadas de la API v1118 tools, una por operación publicada

El servidor MCP no reemplaza la API REST. Cada tool despacha in-process al handler de /v1 que implementa la operación, así que filtros, validación, reglas de negocio y aislamiento por organización son exactamente los mismos. Si estás escribiendo código, usa la API REST. Si estás conectando un asistente, usa esto.

El principio​

Una capacidad existe en el MCP solo si existe en la API pública.

No hay una segunda implementación de nada. La tool llama al handler del endpoint con la identidad que el token del llamador ya probó — la misma persona, la misma organización —, así que corre como correría cualquier solicitud HTTP. Una tool hace lo que el endpoint hace por REST — nunca más.

La consecuencia práctica: lo que hoy solo existe en el panel no se vuelve tool antes de volverse endpoint. Los nombres siguen el patrón dunning_<recurso>_<verbo> — dunning_charges_list, dunning_charges_notify, dunning_agreements_accept.

tools/list devuelve solo las tools que este llamador puede ejecutar: se filtran por los permisos de panel de la persona dueña del token y por el alcance del propio token. A un agente no se le informa de capacidades que solo le darían una negativa. Las reglas están en Autenticación.

Primeros pasos​

  1. Apunta tu cliente a la URL del servidor — ve Endpoints y Clientes.

  2. Autoriza. El cliente abre el inicio de sesión de Kobana; entra con una cuenta de la organización y autoriza el acceso. Para un cliente sin OAuth, o para que un agente escriba, crea un token personal. Ve Autenticación.

  3. Confirma la conexión. Pregúntale al asistente "¿qué organización estoy usando en Régua de Cobrança?" — llama a dunning_me, que responde la persona, la organización, los scopes y el vencimiento del token. O, con un token emitido para el MCP a mano:

    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. Explora la documentación — el catálogo completo está en Tools.

Próximos pasos​

  • Autenticación — el flujo OAuth, el token personal, los permisos de la persona, el alcance del token y los modos de falla.
  • Endpoints — URLs por ambiente y rutas servidas.
  • Transporte — JSON-RPC, las dos eras del protocolo, cabeceras y métodos.
  • Resources y prompts — documentos por URI, guiones listos, autocompletado y la confirmación de tools destructivas.
  • Clientes — cómo conectar Claude Code, clientes por archivo y por URL.
  • Listado y paginación — page, per_page, sort_by, include y filtros.
  • Errores — los dos canales de falla, y por qué la diferencia importa.
  • Límite de solicitudes — los dos buckets por persona.
  • Idempotencia — idempotency_key en las escrituras.
  • Tools — el catálogo de las 118 tools.