Autenticación

El servidor MCP acepta un Bearer token en la cabecera Authorization, y nada más — sin cookie, sin certificado de cliente.

:::warning Nunca en la URL Un token en la query string (access_token, token, bearer, bearer_token, id_token, api_key o apikey) no autentica, aunque venga junto a una cabecera válida: la solicitud responde 401 con error="invalid_request" en WWW-Authenticate. Un token en la URL se filtra en logs de proxy y CDN, en el Referer y en el historial — la especificación de autorización de MCP y la RFC 6750 lo prohíben. :::

Ese token es un access token emitido por el authorization server de Kobana (https://account.kobana.com.br, la Cuenta Kobana): un JWT firmado en RS256 y emitido para este recurso, cuyo aud es https://mcp.dunning.kobana.com.br. Llega por uno de dos caminos — el flujo OAuth, que hace el propio cliente, o un token personal que creas en tu cuenta Kobana — y se verifica igual en los dos casos.

Authorization: Bearer eyJhbGciOiJSUzI1NiIs…

:::info Cada superficie tiene su propia audience Un token emitido para el MCP no vale en la API REST (api.dunning.*), y un token de la API se rechaza aquí con 401. Un token cuyo aud lista más de un valor también se rechaza. Es lo que impide que el token entregado a un asistente se reutilice contra la API — y al revés. :::

Dos formas de conectarse

	Flujo OAuth	Token personal
Cómo lo obtienes	Pegas la URL en el cliente; abre el inicio de sesión de Kobana y autorizas	Lo creas en Cuenta Kobana → Tokens y Acceso → Nuevo Token Personal: app Régua de Cobrança, uso MCP, recursos y accesos, validez
Cómo lo usa el cliente	Por su cuenta, después de la autorización	Lo pegas en el cliente como `Authorization: Bearer <token>`
Validez	La define el authorization server de Kobana	De 7 días a 1 año, a tu elección
Alcance	Solo el nivel de acceso — hoy, `read`	Los recursos y accesos que marcaste
Bueno para	Claude, ChatGPT, IDEs y cualquier cliente con OAuth	Clientes sin soporte de OAuth, scripts y agentes que necesitan escribir

El token personal tiene que crearse con el uso MCP. Un token creado para el uso API REST tiene la audience de la API y aquí se rechaza con 401 — y lo contrario también vale.

El flujo OAuth

No ejecutas ninguno de estos pasos: el cliente MCP (Claude, ChatGPT, un IDE) lo hace todo solo a partir de la URL. Están aquí para cuando algo falle a mitad de camino.

Desafío. Una solicitud sin token recibe 401 con el desafío que todo resource server OAuth 2.1 debe enviar (RFC 9728):

WWW-Authenticate: Bearer realm="kobana-dunning-mcp",
                  error="invalid_token",
                  resource_metadata="https://mcp.dunning.kobana.com.br/.well-known/oauth-protected-resource"

Metadata del recurso. El cliente lee el documento señalado. Es público y no lleva ningún secreto — solo punteros:

curl https://mcp.dunning.kobana.com.br/.well-known/oauth-protected-resource

{
  "resource": "https://mcp.dunning.kobana.com.br",
  "authorization_servers": ["https://account.kobana.com.br"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": [
    "dunning/agreements",
    "dunning/audit_logs",
    "…",
    "dunning/webhook_endpoints",
    "read"
  ],
  "resource_documentation": "https://docs.dunning.com.br/en/mcp/overview/introduction"
}

scopes_supported lista los 21 recursos dunning/<recurso> y read. Nunca trae dunning/all ni los verbos de escritura: el authorization server no los concede a un cliente de registro dinámico.

Metadata del authorization server (RFC 8414), en https://account.kobana.com.br.
Registro dinámico del cliente (RFC 7591). El cliente se registra solo.
Autorización con PKCE y resource (RFC 8707). Inicias sesión en Kobana, eliges la organización (si tienes más de una) y autorizas.
Token. El cliente cambia el código por un access token y lo envía en cada solicitud, renovándolo cuando vence.

El token lleva quién eres (sub) y la cuenta Kobana que autorizaste (org), que es la organización en Régua de Cobrança. Es el org lo que delimita los datos — ninguna tool acepta organización como argumento. Un token cuyo org no corresponde a ninguna organización en Régua de Cobrança recibe 403 unknown_organization.

Autorización: los permisos de la persona

Aquí está la diferencia más importante con la API REST. En la API, el token actúa con la autoridad de la integración — los permisos de la clave. En el MCP, las tools se filtran por los permisos de panel de la persona dueña del token (el sub) en esa organización, leídos en cada solicitud. El techo es siempre lo que esa persona puede hacer en la interfaz.

La persona se localiza por la identidad Kobana registrada cuando entra en el panel de Régua de Cobrança con su cuenta Kobana. Por eso, quien nunca entró en Régua de Cobrança con la cuenta Kobana no tiene tools: la llamada responde key_owner_not_member. Lo resuelves entrando una vez en el panel con la cuenta Kobana, o pidiendo una invitación a la organización. Una invitación a otra organización también vale: el vínculo se encuentra por el e-mail de la persona.

Situación	Resultado
La persona no es miembro de la organización	Niega todas las tools (`key_owner_not_member`). Entra en el panel con la cuenta Kobana, o pide una invitación.
Vínculo activo	Los permisos y roles de la persona, aplicados tool a tool. `dunning.dashboard.` lo libera todo; `dunning.dashboard.charges.` libera la familia de cobros.
Vínculo inactivo, o sin ningún permiso ni rol	Niega todas las tools (`membership_inactive`).
La consulta de permisos falla	Niega todas las tools. Falla cerrada.

La única excepción es dunning_me, que responde a cualquier token válido — es lo que permite ver, desde el propio cliente, qué persona y qué organización está usando la conexión.

Los recursos administrativos — miembros, roles, claves, configuraciones — nunca son alcanzables por token, y ni siquiera tienen tool.

Los permisos se leen en cada llamada, así que revocar un rol en el panel vale ya en la llamada siguiente, sin esperar a que el token venza.

Una tool que el llamador no puede ejecutar no aparece en tools/list. Cuando tools/call rechaza, el código dice quién lo resuelve:

Código	Quién lo resuelve
`insufficient_scope`	Usar un token que alcance el recurso con el acceso pedido — por ejemplo, un token personal con escritura en ese recurso — o autorizar de nuevo.
`insufficient_permission`	Un admin de la organización, concediendo el permiso (el error dice cuál).
`membership_inactive`	Reactivar a la persona — ningún permiso arregla un vínculo muerto.
`key_owner_not_member`	La persona entra en el panel de Régua de Cobrança con su cuenta Kobana, o pide una invitación.

:::tip Postura recomendada para agentes Autoriza el cliente con una cuenta que tenga solo los permisos que el agente necesita. Un cliente autorizado por un analista de solo lectura expone solo las tools de lectura, haga lo que haga el modelo del otro lado. :::

Alcance del token

Además de los permisos, el MCP aplica el alcance que trae el token. Las dos verificaciones se suman: una tool solo aparece si las dos lo permiten. Lectura es tool de lectura, resource, prompt y completion; escritura es todo lo demás, destructivas incluidas. El token tiene dos formas.

Token sin recursos dunning/… — el caso del flujo OAuth y de los clientes de registro dinámico. Vale solo el nivel de acceso: lectura con read, write o all; escritura con write o all.

:::info Los clientes conectados por el flujo OAuth hoy solo leen El authorization server concede solo read a los clientes de registro dinámico — Claude, ChatGPT, el MCP Inspector, IDEs. Para ellos, el MCP lista solo las tools de lectura, y una tool que escribe devuelve insufficient_scope. Para que un agente escriba hoy, usa un token personal con acceso de escritura a los recursos que necesita. :::

Token con recursos dunning/… — el caso del token personal. Los recursos definen hasta dónde llega el token, y read/write/all valen solo dentro de ellos:

Alcance del token	Resultado
`dunning/charges dunning/people read write`	Lee y escribe cobros y deudores — y nada más
`dunning/charges read`	Solo lee cobros
`dunning/all read`	Lee todo, no escribe nada

delete, import y export solos no cuentan como escritura. Un token que no trae ni recurso ni nivel de acceso no alcanza nada — solo dunning_me, disponible para cualquier token válido.

Los 21 recursos de scope son: agreements, audit_logs, charges, classifications, collection_rules, disputes, email_layouts, exports, imports, interactions, metrics, negativations, negotiation_campaigns, notification_channels, notification_preferences, notifications, people, protests, tasks, templates y webhook_endpoints. El recurso de cada tool es el primer segmento de la ruta de la API (/collection-rules/... → collection_rules): los contactos de un deudor están en people, las campañas de negociación en negotiation_campaigns y los pasos de una regla en collection_rules.

La verificación de alcance se repite en /v1 cuando la tool se despacha — defensa en profundidad. Un rechazo en ese punto vuelve como INSUFFICIENT_SCOPE, con el cuerpo de la API.

Revocación del token personal

Revocar un token personal en tu cuenta Kobana no corta el acceso en el momento: Régua de Cobrança verifica el token localmente, sin consultar a Kobana en cada llamada, y sigue aceptándolo hasta su vencimiento. Por eso:

elige la validez más corta que el uso permita;
marca solo los recursos y accesos que el agente necesita;
para cortar un agente de inmediato, desactiva a la persona en la organización — los permisos se leen en cada llamada y valen al instante.

Modos de falla

HTTP	`code`	Causa
400	`-32022` (JSON-RPC)	Versión del protocolo no soportada; `data.supported` lista las que sí. Ve Transporte.
400	`-32020` (JSON-RPC)	Una cabecera de la era `2026-07-28` no coincide con el cuerpo.
401	`UNAUTHORIZED`	Token ausente, malformado, inválido, vencido, emitido para otro recurso (por ejemplo, para la API REST) o enviado en la URL.
403	`unknown_organization`	El token es válido, pero su organización no existe en Régua de Cobrança.
403	`FORBIDDEN`	`Origin` de navegador que no es el propio servidor (`origin_not_allowed`). Sin `Origin`, la solicitud pasa.
404	`NOT_FOUND`	La solicitud llegó por un host que no sirve MCP.
413	`-32600` (JSON-RPC)	Cuerpo de más de 2 MB (`Request body too large`) — el mismo techo de la API v1.
429	`RATE_LIMITED`	Límite de solicitudes alcanzado — ve Límite de solicitudes.
503	`SERVICE_UNAVAILABLE`	No pudimos hablar con el authorization server. Es de nuestro lado: reintenta después del `Retry-After`.

Todo 401 lleva el desafío WWW-Authenticate de arriba, que devuelve al cliente al flujo OAuth.

Las negativas de permiso y de alcance no son errores HTTP: vuelven como resultado de tool marcado isError, para que el modelo las lea y reaccione — ve Errores.

Dos formas de conectarse​

El flujo OAuth​

Autorización: los permisos de la persona​

Alcance del token​

Revocación del token personal​

Modos de falla​