Servidor MCP

Finova expone un servidor Model Context Protocol (MCP) para que clientes de IA — Claude.ai (web, OAuth), Claude Desktop, ChatGPT (custom connector), Cursor, Continue, Cline, y cualquier cliente compatible — se conecten directamente a tu cuenta y le permitan a la IA consultar tus datos y generar reportes.

Estado actual (MVP): sólo lectura. La IA puede listar y consultar datos + generar reportes, pero no puede crear, editar ni borrar. Las mutaciones llegan en una fase posterior.

Endpoint

POST https://developers.fi-nova.com/api/mcp/v1

Transporte: Streamable HTTP (spec MCP 2025-03-26). JSON-RPC 2.0 sobre POST.
Content-Type: application/json.
Auth: dos opciones, ambas soportadas en paralelo:
- API key estática — header Authorization: Bearer finova_sk_<secret>. La misma key que la API REST. Genera una en app.fi-nova.com → Settings → Developers. Recomendada para scripts y clientes que pegas el token a mano (Claude Desktop, Cursor, Continue, ChatGPT custom connector privado).
- OAuth 2.1 + PKCE — header Authorization: Bearer finova_oat_<secret>, donde el access token sale del flow OAuth. Recomendada para clientes web que descubren OAuth automáticamente (Claude.ai). El usuario nunca pega una API key — el access token rota solo y se puede revocar.

GET sobre el mismo URL devuelve un handshake público (sin auth) útil para verificar que el servidor está vivo.

Flow OAuth 2.1

Cualquier cliente compatible con la spec MCP 2025-03-26 descubre los endpoints sin configuración manual:

GET https://developers.fi-nova.com/.well-known/oauth-protected-resource — metadata del recurso (RFC 9728).
GET https://developers.fi-nova.com/.well-known/oauth-authorization-server — metadata del authorization server (RFC 8414).
POST https://developers.fi-nova.com/oauth/register — dynamic client registration (RFC 7591). Devuelve un client_id opaco (fcli_*). No emitimos client_secret — el flow es público con PKCE S256 obligatorio.
GET https://developers.fi-nova.com/authorize?response_type=code&client_id=fcli_…&redirect_uri=…&code_challenge=…&code_challenge_method=S256&state=…&scope=read-customers+read-incomes+… — el usuario inicia sesión en developers.fi-nova.com, escoge la empresa que quiere conectar y aprueba los scopes pedidos.
POST https://developers.fi-nova.com/oauth/token con grant_type=authorization_code + code_verifier — devuelve access_token (finova_oat_*, 1h) y refresh_token (finova_ort_*, 30 días, rota en cada uso).
Llamadas a /api/mcp/v1 con Authorization: Bearer finova_oat_*.
Refresh con grant_type=refresh_token cuando el access token expira.

Los scopes disponibles son los mismos slugs que las API keys (<action>-<resource>). El usuario aprueba un subset por sesión y siempre puede revocar el acceso desde Finova.

Scopes y autorización

Cada tool requiere un scope en el formato <action>-<resource>. El servidor MCP:

Filtra tools/list para mostrar sólo las tools cuyo scope coincida con los permisos de tu API key. Esto evita que el LLM intente llamarlas y queme turns con errores 403.
Rechaza tools/call con código -32001 Forbidden si la API key no tiene el scope requerido.

Catálogo de tools

Tool	Scope requerido	Devuelve
`list_customers`	`read-customers`	Clientes con búsqueda por nombre/email/teléfono.
`list_products`	`read-products`	Catálogo con búsqueda y filtros.
`list_leads`	`read-leads`	Pipeline de prospección (CRM).
`list_accounts`	`read-accounts`	Cuentas con balance actual + totales por moneda.
`list_incomes`	`read-incomes`	Ingresos con filtros por fecha, cuenta, cliente.
`list_expenses`	`read-expenses`	Egresos con filtros por fecha, cuenta, proveedor.
`list_calendar_events`	`read-calendar_events`	Eventos del calendario por rango.
`get_company`	`read-company`	Info básica de la empresa + módulos activados.
`get_balance_sheet`	`read-reports`	Balance general a una fecha de corte.
`get_income_statement`	`read-reports`	Estado de resultados (P&L) por rango.
`get_cash_flow`	`read-reports`	Flujo de efectivo por rango.

Recomendación: para un asistente IA generalista, crea una API key con los scopes read-customers, read-products, read-incomes, read-expenses, read-accounts, read-reports, read-company.

Métodos JSON-RPC soportados

Method	Descripción
`initialize`	Handshake. Devuelve capabilities + serverInfo.
`notifications/initialized`	Ack del cliente tras initialize. Sin respuesta.
`notifications/cancelled`	Cancelación. Sin respuesta.
`ping`	Health check. Devuelve `{}`.
`tools/list`	Lista las tools que esta API key puede usar.
`tools/call`	Ejecuta una tool.

Aún no soportado: resources/*, prompts/*, logging/*, roots/*, sampling/*.

Cliente: Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o el equivalente en tu sistema:

json

{
  "mcpServers": {
    "finova": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://developers.fi-nova.com/api/mcp/v1",
        "--transport",
        "http-only",
        "--header",
        "Authorization: Bearer finova_sk_TU_SECRETO"
      ]
    }
  }
}

Claude Desktop sólo soporta servidores MCP por stdio, por eso usamos mcp-remote como proxy hacia el endpoint HTTP. Requiere tener Node.js / npx instalado. Reinicia Claude Desktop después de guardar; las tools de Finova aparecen en el selector de servidores.

Cliente: Claude.ai (OAuth)

En claude.ai (web, planes Pro / Team / Enterprise): Settings → Conectores → Agregar conector personalizado.

Nombre: Finova
URL del servidor MCP remoto: https://developers.fi-nova.com/api/mcp/v1
Configuración avanzada: déjalo cerrado. No pegues token.

Al darle Agregar, Claude.ai descubre los metadata OAuth, hace dynamic client registration y te redirige a developers.fi-nova.com/authorize. Inicia sesión con tu cuenta de Finova, escoge la empresa que quieres conectar y aprueba los scopes. De regreso en Claude.ai verás "Finova" en tus conectores con las tools disponibles.

A diferencia del flow Bearer, no compartes ninguna API key con Claude.ai. El access token (finova_oat_*) rota automáticamente y puedes revocar el acceso en cualquier momento desde app.fi-nova.com → Settings → Developers → MCP Server.

Cliente: ChatGPT (custom connector)

Settings → Connectors → Add custom connector:

URL: https://developers.fi-nova.com/api/mcp/v1
Auth type: Bearer token
Token: finova_sk_TU_SECRETO

ChatGPT requiere OAuth para conectores publicados en el marketplace — como conector privado para tu propio uso, el Bearer con API key basta. Finova ya soporta OAuth 2.1 + PKCE (ver el flow descrito arriba); cuando publiquemos un conector oficial de ChatGPT en el marketplace usará ese flow.

Cliente: Cursor / Continue / Cline

Cualquier cliente compatible con MCP remoto vía HTTP funciona. Configuración típica:

json

{
  "name": "finova",
  "transport": {
    "type": "http",
    "url": "https://developers.fi-nova.com/api/mcp/v1",
    "headers": { "Authorization": "Bearer finova_sk_TU_SECRETO" }
  }
}

Prueba rápida desde la terminal

Handshake

bash

curl -sX POST https://developers.fi-nova.com/api/mcp/v1 \
  -H "Authorization: Bearer finova_sk_TU_SECRETO" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "curl-test", "version": "0.1" }
    }
  }'

Listar tools disponibles

bash

curl -sX POST https://developers.fi-nova.com/api/mcp/v1 \
  -H "Authorization: Bearer finova_sk_TU_SECRETO" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Generar estado de resultados

bash

curl -sX POST https://developers.fi-nova.com/api/mcp/v1 \
  -H "Authorization: Bearer finova_sk_TU_SECRETO" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_income_statement",
      "arguments": {
        "start_on": "2026-01-01",
        "end_on":   "2026-03-31"
      }
    }
  }'

Formato de respuesta

Las tools devuelven contenido envuelto en content (texto JSON serializado, para clientes legacy) y en structuredContent (objeto parseado, spec 2025-03-26) — así los clientes modernos no tienen que parsear strings dos veces.

json

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      { "type": "text", "text": "{\"customers\":[...],\"meta\":{...}}" }
    ],
    "structuredContent": {
      "customers": [...],
      "meta": { "page": 1, "per_page": 25, "total": 137 }
    },
    "isError": false
  }
}

Cuota por plan

MCP es una feature de los planes pagados de Finova. La cuota está incluida en tu plan y se mide por ciclo de facturación (mensual o anual, según el plan).

Plan	Tool calls por ciclo
Free / sin suscripción	0 (feature no disponible)
Plan Starter	500
Planes empresariales	Configurable — contáctanos

Cada tools/call cuenta como 1 llamada, exitosa o no — las que rebotan por scope insuficiente o args inválidos también consumen cuota para evitar probing barato.
El contador se resetea automáticamente al renovar la suscripción.
Si tu plan no incluye MCP, el servidor responde inmediatamente con -32004 QuotaExceeded y data.available = false — eso es señal para que tu cliente IA notifique al usuario que necesita actualizar el plan.
La pestaña Settings → Developers → MCP Server en app.fi-nova.com muestra el contador en vivo, paywall si no aplica, y un preview del catálogo de tools.

Códigos de error

Estándar JSON-RPC + algunos específicos:

Código	Significado
`-32700`	Parse error — el JSON no parsea.
`-32600`	Invalid request — falta `jsonrpc: "2.0"` o estructura inválida.
`-32601`	Method not found.
`-32602`	Invalid params — argumentos no pasaron validación.
`-32603`	Internal error.
`-32001`	Forbidden — la API key no tiene el scope que la tool requiere.
`-32002`	Tool no encontrada.
`-32003`	Execution failed — la tool corrió pero terminó con error (ej. rango inválido).
`-32004`	Quota exceeded — se agotó la cuota del ciclo o el plan no incluye MCP. El `data` incluye `limit`, `used`, `available` (false ⇒ falta plan) y `resets_at`.

Auth falla a nivel HTTP (401 invalid_key) — el JSON-RPC nunca arranca cuando la key es inválida.

Observabilidad

Desde la UI en app.fi-nova.com → Settings → Developers → MCP Server puedes ver:

URL del endpoint (con botón copiar).
Catálogo de tools con sus scopes.
Snippets de conexión para cada cliente.
Logs de las últimas 25 invocaciones (tool, status, duración, args).
Tasa de éxito de las últimas 24 horas.

Roadmap

Fase	Scope	Disponible
1 (MVP)	Read-only: `list_` + `get_` (reportes)	✅ Ahora
2	OAuth 2.1 + dynamic client registration (Claude.ai, conectores web)	✅ Ahora
3	Search tools (full-text para clientes/productos/leads)	Próximo
4	Mutaciones limitadas: `create_customer`, `create_lead`, `create_income`, `create_expense`	Después
5	`resources/*` (acceso documental: facturas, contratos, archivos)	Más adelante

Limitaciones del MVP

Read-only — ninguna tool muta datos.
Sin SSE / streaming — cada llamada devuelve respuesta completa.
Sin resources/* ni prompts/*.
Stateless — no usamos Mcp-Session-Id headers. Si el cliente lo envía, se ignora.

Servidor MCP ​

Endpoint ​

Flow OAuth 2.1 ​

Scopes y autorización ​

Catálogo de tools ​

Métodos JSON-RPC soportados ​

Cliente: Claude Desktop ​

Cliente: Claude.ai (OAuth) ​

Cliente: ChatGPT (custom connector) ​

Cliente: Cursor / Continue / Cline ​

Prueba rápida desde la terminal ​

Handshake ​

Listar tools disponibles ​

Generar estado de resultados ​

Formato de respuesta ​

Cuota por plan ​

Códigos de error ​

Observabilidad ​

Roadmap ​

Limitaciones del MVP ​

Servidor MCP

Endpoint

Flow OAuth 2.1

Scopes y autorización

Catálogo de tools

Métodos JSON-RPC soportados

Cliente: Claude Desktop

Cliente: Claude.ai (OAuth)

Cliente: ChatGPT (custom connector)

Cliente: Cursor / Continue / Cline

Prueba rápida desde la terminal

Handshake

Listar tools disponibles

Generar estado de resultados

Formato de respuesta

Cuota por plan

Códigos de error

Observabilidad

Roadmap

Limitaciones del MVP