Autenticación

El servidor MCP acepta un Bearer token en el encabezado Authorization, y nada más — sin cookie, sin certificado de cliente, sin token en la URL. Una solicitud con ?access_token= (o ?token= y similares) se rechaza con 401, incluso junto a un encabezado válido: en la URL el token se filtra a logs, historial del navegador e intermediarios.

Ese token es un access token OAuth 2.1 emitido por el Authorization Server de Kobana (https://account.kobana.com.br), un JWT firmado en RS256 y emitido para este recurso: su aud es https://mcp.finance.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 de la misma forma en los dos casos.

Authorization: Bearer eyJhbGciOiJSUzI1NiIs…

:::info Cada superficie tiene su audience Un token emitido para el MCP no vale en la API REST (api.finance.*), y un token de la API no vale aquí. Es lo que impide que el token entregado a un asistente se reutilice contra la API — y al revés. :::

Dos formas de conectar

	Flujo OAuth	Token personal
Cómo lo obtienes	Pegas la URL en el cliente; abre el login de Kobana y autorizas	Lo creas en Cuenta Kobana → Tokens y Acceso → Nuevo Token Personal: app Finanzas Inteligentes, uso MCP, recursos y accesos, validez
Cómo lo usa el cliente	Solo, después de la autorización	Lo pegas en el cliente como `Authorization: Bearer <token>`
Validez	Corta, renovada por el cliente	De 7 días a 1 año, elegida por ti
Scope	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 a OAuth, scripts y agentes que necesitan escribir

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

El workspace

El org del token indica la organización; el workspace en el que actúa cada tool se decide en cada llamada, en este orden:

Orden	De dónde viene
1	El argumento `workspace_id` de la tool, cuando viene en la llamada
2	El workspace predeterminado de la conexión (abajo)
—	Ninguno de los dos: la tool devuelve el error `workspace_required`

La URL del servidor no necesita workspace — https://mcp.finance.kobana.com.br basta —, y conectarse nunca falla por falta de uno. Para saber dónde puede actuar, el agente llama a finance_workspaces_list, sin argumentos: lista los workspaces de la organización que alcanza la persona del token.

{ "data": [
  { "id": "2b93f876-769a-4bdc-b23e-304957f313b4", "name": "Matriz", "default": true },
  { "id": "7c1d0e52-…", "name": "Filial Sul", "default": false }
] }

Todas las demás tools — salvo finance_schemas_get y la propia finance_workspaces_list — aceptan el argumento opcional workspace_id (uuid):

{ "name": "finance_payables_list",
  "arguments": { "workspace_id": "2b93f876-769a-4bdc-b23e-304957f313b4", "limit": 10 } }

El workspace predeterminado

Es el que vale cuando la llamada no trae workspace_id, y es el que aparece marcado default: true en finance_workspaces_list:

Dónde	Ejemplo
Encabezado `X-Workspace-Id` (opcional)	`X-Workspace-Id: 2b93f876-769a-4bdc-b23e-304957f313b4`
Parámetro en la URL del servidor (opcional)	`https://mcp.finance.kobana.com.br/?workspace_id=2b93f876-…`
Ninguno de los dos	El único workspace que alcanza la persona, si alcanza exactamente uno

El encabezado y el parámetro de URL se siguen aceptando, pero ahora son opcionales y solo definen el predeterminado: el argumento workspace_id siempre les gana. En cualquier caso el valor es selector, no concesión — se verifica contra la organización del token y el acceso de la persona:

Sin workspace_id y sin predeterminado — la persona alcanza varios workspaces —, la tool devuelve workspace_required. Es un resultado de tool con isError: true, no un error HTTP:
```
{ "error": { "code": "workspace_required", "message": "…" } }
```
Un workspace_id que la persona no alcanza, o que no existe, devuelve el error de tool workspace_access_denied — la misma respuesta en ambos casos.
Un encabezado o parámetro de URL con un workspace de otra organización sigue rechazado con HTTP 403 UNKNOWN_WORKSPACE.

Los resources (kobana://finance/…) y las completions no tienen argumento de workspace: usan el predeterminado de la conexión. Sin él, leer un resource de registro falla con workspace_required — usa las tools —, y las completions no sugieren nada. Ver Resources y prompts.

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-finance-mcp",
                  error="invalid_token",
                  resource_metadata="https://mcp.finance.kobana.com.br/.well-known/oauth-protected-resource"

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

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

{
  "resource": "https://mcp.finance.kobana.com.br",
  "authorization_servers": ["https://account.kobana.com.br"],
  "bearer_methods_supported": ["header"],
  "resource_documentation": "https://docs.finance.kobana.com.br/pt/mcp/overview/introduction"
}

No hay scopes_supported: la Cuenta Kobana todavía no publica los scopes de Finanzas Inteligentes, y un cliente que los pidiera sería rechazado en la autorización.

Metadata del Authorization Server (RFC 8414), en https://account.kobana.com.br/.well-known/oauth-authorization-server.
Registro dinámico del cliente (RFC 7591). El cliente se registra solo; la pantalla de consentimiento avisa que no es una app verificada.
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 de vida corta y pasa a enviarlo en cada solicitud, renovándolo cuando expira.

El token lleva quién eres (sub) y la organización que autorizaste (org); el workspace viene de cada llamada, como arriba. Ninguna tool acepta organización como argumento.

Dos ejes de autorización

Lo que ve un llamador es más estrecho que el catálogo, por dos filtros independientes. Ninguno de los dos puede ampliar la superficie.

Eje 1 — el scope del token

El techo del cliente, en el claim scope. Lectura es tool de lectura, resource, prompt y completion; escritura es todo lo demás, destructivas incluidas. Mover dinero es un escalón por encima de la escritura.

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

Scope del token	Resultado
`finance/payables finance/people read write`	Lee y escribe cuentas por pagar y personas — y nada más
`finance/payables read`	Solo lee cuentas por pagar
`finance/all read`	Lee todo, no escribe nada
`finance/payables finance/payable_dispatches read write`	También envía cuentas por pagar al banco

Enviar al banco y cobrar exigen el recurso propio — finance/payable_dispatches y finance/receivable_charges — con write o all; finance/payables write no basta. delete, import y export por sí solos no cuentan como escritura.

Token sin recursos — el caso del flujo OAuth. Vale solo el nivel de acceso: lectura con read, write o all; escritura con write o all; mover dinero solo con all.

:::info Los clientes conectados por el flujo OAuth quedan solo con lectura El Authorization Server concede solo read a los clientes registrados dinámicamente — Claude, ChatGPT, el MCP Inspector, IDEs. Para ellos, el MCP lista solo las tools de lectura, y una tool que escribe vuelve insufficient_scope. Para que un agente escriba hoy, usa un token personal con acceso de escritura en los recursos que necesita. :::

La misma regla vale en la API REST — ver Alcances.

Eje 2 — los permisos de la persona del token

El sub del token es la persona que consintió. En el MCP, las tools se estrechan a lo que esa persona puede hacer en el panel de la organización, resuelto en cada solicitud — las mismas funciones y permisos de la pantalla Miembros.

Situación	Resultado
La persona nunca entró a Finanzas Inteligentes, o no es miembro de la organización	Niega todas las tools. Quien no es miembro no alcanza nada por el MCP.
Miembro activo, con acceso al workspace	Sus permisos, tool por tool. El dueño (``) libera todo; `payables.` libera la familia.
Miembro activo sin acceso al workspace	Niega todas las tools de ese workspace.
Miembro suspendido, con invitación pendiente, eliminado o sin ningún permiso	Niega todas las tools. Un token que sobrevive al acceso de la persona es justo el caso a cerrar.
La consulta de permisos falla	Niega todas las tools. Falla cerrada.

Los permisos se leen en cada llamada: quitar un permiso en el panel vale desde la siguiente tool, sin esperar a que el token expire.

:::tip Postura recomendada para agentes Conecta el asistente con una cuenta que solo tiene los permisos que el agente necesita y, en un token personal, marca solo los recursos y accesos que va a usar. Los dos ejes se suman: el token de un analista de solo lectura expone solo las tools de lectura, haga lo que haga el modelo del otro lado. :::

Cómo se componen los dos

El conjunto final es la intersección: tools ∩ scopes del token ∩ permisos de la persona. Una tool que el llamador no puede ejecutar no se lista.

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.
`insufficient_permission`	Un admin de la organización, concediendo el permiso (el error lo nombra).
`workspace_required`	El agente pasa `workspace_id` — uno de los `id` de `finance_workspaces_list` —, o la conexión define un workspace predeterminado.
`workspace_access_denied`	Un admin concede el workspace a la persona, o el agente pasa otro `workspace_id`.
`membership_inactive`	Incluir a la persona en la organización o reactivarla — ningún permiso arregla una membresía que no existe o está inactiva.

:::caution Lo que el eje 2 no cubre El estrechamiento por permiso vale solo para el MCP. Un token de la API, llamado directo en api.finance.*, sigue limitado solo por sus scopes. :::

Seguridad › Canales

Las reglas de la pestaña Seguridad › Canales siguen valiendo por encima de los dos ejes — las aplica el propio endpoint. Un agente de IA actúa por el canal MCP - Inteligencia Artificial, donde, por defecto, enviar al banco empieza cerrado: finance_payables_send_to_bank solo funciona después de que la solicitud sea aprobada.

Revocación del token personal

Revocar un token personal en tu Cuenta Kobana no corta el acceso en el momento: Finanzas Inteligentes verifica el token por sí mismo, sin consultar a Kobana en cada llamada, y el token sigue aceptado hasta su validez. 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, suspende o elimina a la persona en la organización, o quítale el acceso al workspace — 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, en el encabezado `MCP-Protocol-Version` o en el `_meta`; `data.supported` lista las que sí. Ver Transporte.
401	`UNAUTHORIZED`	Token ausente, malformado, inválido, revocado, expirado, emitido para otro recurso (la API, por ejemplo) o enviado en la URL (`?access_token=`).
403	`UNKNOWN_ORGANIZATION` / `UNKNOWN_WORKSPACE`	El `org` del token no es un cliente, o el workspace de `X-Workspace-Id` / `?workspace_id=` no es de la organización.
403	`FORBIDDEN`	`Origin` fuera de la allowlist (`origin_not_allowed`).
404	`NOT_FOUND`	La solicitud llegó por un host que no sirve MCP, o pidió un camino que no existe en el servidor.
429	`RATE_LIMITED`	Límite de solicitudes alcanzado — ver Límite de solicitudes.
503	`SERVICE_UNAVAILABLE`	La Cuenta Kobana no respondió para validar el token. No es un problema del token: inténtalo de nuevo después del `Retry-After`.

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

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

Host y borde

El endpoint solo es alcanzable por mcp.finance.* — nunca por el host de la app ni por el de la API, que apuntan al mismo origen. Cualquier otro camino responde 404, siempre en JSON y para cualquier método — { "error": { "code": "NOT_FOUND", "message": "Not found." } }, nunca una página HTML. El identificador de recurso OAuth se deriva de la configuración del servidor, nunca del Host de la solicitud, para que un Host falsificado no pueda apuntar un cliente a otro identificador.

Dos formas de conectar​

El workspace​

El workspace predeterminado​

El flujo OAuth​

Dos ejes de autorización​

Eje 1 — el scope del token​

Eje 2 — los permisos de la persona del token​

Cómo se componen los dos​

Seguridad › Canales​

Revocación del token personal​

Modos de falla​

Host y borde​