Saltar al contenido principal

Introducción

El servidor MCP de Finanzas Inteligentes es un servidor Model Context Protocol remoto que expone las operaciones de la API pública — cuentas por pagar y por cobrar, movimientos, conciliaciones, cuentas financieras, flujo de caja y registros — como tools que un cliente de IA puede llamar. Lo conectas por URL; no hay nada que instalar.

Se sirve en un host propio, mcp.finance.kobana.com.br, en el mismo dominio que la API, con transporte Streamable HTTP en modo stateless y autenticación por Bearer token emitido para el MCP por la Cuenta Kobana. No interviene ningún certificado de cliente.

:::info Disponibilidad El servidor, sus 95 tools, los resources y los prompts están implementados, y la autenticación es por el Authorization Server de Kobana: por el flujo OAuth 2.1, en el que el cliente recibe solo la URL y hace el login por sí mismo, o por un token personal creado en tu Cuenta Kobana. El borde dedicado (distribution mcp.finance.*, 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óntoken y X-Workspace-Id, fuera de bandasolo una URL; el workspace va en cada llamada
TransporteHTTPS/RESTStreamable HTTP (JSON-RPC 2.0)
AutenticaciónBearer token emitido para la APIOAuth 2.1 o token personal, siempre emitido para el MCP
Autorizaciónscope del tokenscope del token y permisos de la persona
Superficielos endpoints de /v195 tools, una por operación de esos endpoints, más resources y prompts sobre ellas

El servidor MCP no reemplaza la API REST. Cada tool despacha in-process al endpoint que implementa la operación, así que filtros, validación, reglas de liquidación, prorrateo y aislamiento por workspace 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 solo existe en el MCP si existe en la API pública.

Nada se implementa dos veces. La tool llama al handler del endpoint con la identidad que el token del llamador ya probó — la misma persona, la misma organización, el mismo workspace —, así que se ejecuta, verifica el scope y audita como lo haría con cualquier solicitud HTTP. Una tool hace lo que el endpoint hace por REST — nunca más.

En la práctica: lo que hoy solo existe en el panel (aprobar pagos, importar extractos, gestionar miembros) no se convierte en tool antes de convertirse en endpoint.

tools/list devuelve solo las tools que este llamador puede ejecutar: las que alcanzan los scopes del token y que la persona del token tiene permiso para hacer en la organización. Un agente no se entera de capacidades que solo le serían negadas. Los dos ejes están en Autenticación.

Primeros pasos​

  1. Apunta tu cliente a la URL del servidor — https://mcp.finance.kobana.com.br, nada más. Ver Endpoints y Clientes.

  2. Autoriza. El cliente abre el login de Kobana; entra con una cuenta de la organización y autoriza el acceso. Ver Autenticación.

  3. Elige el workspace. El agente llama a finance_workspaces_list y pasa el id elegido como workspace_id a las demás tools. Si alcanzas un solo workspace, ese es el predeterminado y el argumento se puede omitir. Ver Autenticación → El workspace.

  4. Lista las tools para confirmar lo que alcanza tu acceso — pídeselo al asistente o, con un token emitido para el MCP en mano:

    curl https://mcp.finance.kobana.com.br/ \
      -H "Authorization: Bearer $MCP_TOKEN" \
      -H "Content-Type: application/json" \
      -H "MCP-Protocol-Version: 2025-06-18" \
      -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

  5. Explora el catálogo en Tools.

Próximos pasos​

  • Autenticación — el flujo OAuth, el token personal, el workspace, el scope y los permisos aplicados, y los modos de falla.
  • Endpoints — URLs por entorno y rutas servidas.
  • Transporte — JSON-RPC, encabezados y métodos.
  • Clientes — cómo conectar Claude Code y clientes por archivo.
  • Listado, filtros y campos — cursor, filters, sort_by, fields.
  • Idempotencia — y las acciones que mueven dinero.
  • Resources y prompts — documentos por URI, guiones listos, autocompletado y la confirmación de tools destructivas.
  • Errores — los dos canales de falla, y por qué importa la distinción.
  • Tools — el catálogo completo.