Saltar al contenido principal

Clientes

Cualquier cliente que hable Streamable HTTP MCP y sepa hacer el flujo OAuth 2.1 del MCP puede conectarse. Solo indicas la URL y el cliente descubre solo dónde autenticarse, abre el login de Kobana en el navegador y guarda el token. Ver Autenticación.

Un cliente sin soporte a OAuth también se conecta, con un token personal: créalo en Cuenta Kobana → Tokens y Acceso → Nuevo Token Personal, con la app Finanzas Inteligentes y el uso MCP, y configura el cliente para enviarlo en el encabezado Authorization: Bearer <token>. Es también el camino para un agente que necesita escribir, ya que por el flujo OAuth el acceso hoy es solo de lectura.

La URL no lleva workspace. El agente elige dónde actuar en cada llamada: finance_workspaces_list lista los workspaces que alcanzas, y las demás tools aceptan workspace_id. Si alcanzas uno solo, ni eso hace falta. Para fijar un workspace predeterminado en la conexión, agrega ?workspace_id= a la URL o, cuando el cliente lo permite, el encabezado X-Workspace-Id — los dos son opcionales. Ver Autenticación → El workspace.

Claude Code​

claude mcp add --transport http kobana-finance https://mcp.finance.kobana.com.br

Después, ejecuta /mcp en una sesión y elige Authenticate para iniciar sesión en Kobana.

Para definir un workspace predeterminado — opcional —, usa la URL con él:

claude mcp add --transport http kobana-finance \
  "https://mcp.finance.kobana.com.br/?workspace_id=$WORKSPACE_ID"

Con un token personal, sin flujo OAuth:

claude mcp add --transport http kobana-finance https://mcp.finance.kobana.com.br \
  --header "Authorization: Bearer <token personal>"

Clientes configurados por archivo​

Los clientes que leen un archivo JSON de configuración piden la URL y el transporte. Por el flujo OAuth, no hay encabezado de autenticación:

{
  "mcpServers": {
    "kobana-finance": {
      "type": "http",
      "url": "https://mcp.finance.kobana.com.br"
    }
  }
}

En la primera conexión el cliente abre el navegador para que autorices. Eliges la organización en la pantalla de consentimiento, y queda grabada en el token; el workspace viene de cada llamada (o del predeterminado, si pones ?workspace_id= en la URL).

Con un token personal, agrega los encabezados — la organización es la de la cuenta en la que creaste el token:

{
  "mcpServers": {
    "kobana-finance": {
      "type": "http",
      "url": "https://mcp.finance.kobana.com.br",
      "headers": {
        "Authorization": "Bearer <token personal>"
      }
    }
  }
}

Para un workspace predeterminado, agrega "X-Workspace-Id": "<uuid>" a headers — opcional.

Trata el archivo como un secreto: quien lo lee usa el token.

Clientes que se conectan por URL​

Claude y ChatGPT conectan un servidor remoto pegando la URL — https://mcp.finance.kobana.com.br, nada más — en la configuración de conectores. El flujo OAuth se ejecuta dentro de la propia app, y el asistente descubre los workspaces solo, con finance_workspaces_list.

Usando Billing junto​

Las tools de este servidor empiezan con finance_, y las de Facturación Automática con billing_; los resources, con kobana://finance/ y kobana://billing/. Los dos servidores conviven en el mismo cliente sin colisión — conecta los dos cuando el agente necesita ambos extremos.

Postura recomendada para agentes​

  • Autoriza con la cuenta correcta. El MCP estrecha las tools a lo que la persona que autorizó puede hacer en el panel. Un cliente autorizado por un analista de solo lectura expone solo las tools de lectura, haga lo que haga el modelo del otro lado. Es la forma más fuerte de restringir un agente.
  • Un token por cliente. Cada cliente hace su propio flujo y recibe su propio token, que solo vale en el MCP — no sirve para llamar a la API REST. Para desconectar un agente, quita su autorización en Kobana sin afectar tus integraciones.
  • Token personal: validez corta y scope mínimo. Marca solo los recursos y accesos que el agente necesita, y la validez más corta que el uso permita: revocar el token en Kobana no corta el acceso antes de su validez — ver Revocación del token personal. Un agente que registra títulos no necesita finance/payable_dispatches.
  • Deja el canal MCP cerrado para pagar. Por defecto, la pestaña Seguridad › Canales no deja que los agentes de IA envíen al banco. Ábrelo solo si es intencional.
  • Empieza en el sandbox. El servidor pide confirmación en las tools destructivas, pero la primera exploración no debe ser en producción.
  • Las tools destructivas piden un cliente que confirme. Borrar, enviar al banco, cobrar, transferir, conciliar o ajustar un saldo solo se ejecuta en un cliente que hable la revisión 2026-07-28 con elicitation de formulario; en los demás, esas tools devuelven confirmation_required y el resto funciona con normalidad. Vea Confirmación de tools destructivas.

Verificando la conexión​

La forma más simple es preguntarle al asistente: "¿en qué workspaces puedes actuar?" — llama a finance_workspaces_list. Después, "¿qué empresas existen en el workspace Matriz?" llama a finance_companies_list con su workspace_id.

Con un token emitido para el MCP — un token personal con uso MCP, por ejemplo —, puedes verificarlo con curl:

# ¿Cuántas tools alcanza este token?
curl -s https://mcp.finance.kobana.com.br/ \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools | length'

# Los workspaces que alcanza la persona del token
curl -s https://mcp.finance.kobana.com.br/ \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"finance_workspaces_list","arguments":{}}}'

# Las empresas de un workspace
curl -s https://mcp.finance.kobana.com.br/ \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"finance_companies_list",
                 "arguments":{"workspace_id":"'"$WORKSPACE_ID"'","fields":["name","cnpj"]}}}'

Si el número de tools es menor de lo que esperabas, son los permisos de quien autorizó o el scope del token — ver Autenticación. No es un error.