ordis-mcp-server

Servidor MCP de solo lectura para la API contable de Ordis SpA. Expone cada endpoint de https://ordis.cl/api/v1 como una tool tipada, para consultar la contabilidad de forma nativa desde Claude (Claude Code / Claude Desktop) sin adivinar rutas.

El servidor no guarda el token: lo lee de la variable de entorno ORDIS_API_KEY y actúa solo como cliente HTTP. Autentica únicamente por header Authorization: Bearer.

Requisitos

• Node.js 18 o superior (usa fetch nativo).
• Un token de la API de Ordis (ordis_sk_...). Se genera en el portal: ordis.cl → Acceso API a tus datos (/portal/api-keys) → Crear llave. Se muestra una sola vez — guárdala como variable de entorno, nunca en un archivo versionado.

Instalar y compilar

npm install
npm run build

Genera dist/index.js (el ejecutable del servidor).

Probar en local (MCP Inspector)

ORDIS_API_KEY="ordis_sk_..." npx @modelcontextprotocol/inspector node dist/index.js

Abre la UI del Inspector, lista las 11 tools y prueba una llamada (ej. ordis_get_kpis con periodo: "2026-07").

Conectar a Claude

Opción 1 — Claude Code (CLI)

claude mcp add ordis \
  --env ORDIS_API_KEY=ordis_sk_TU_TOKEN \
  -- node /ruta/absoluta/ordis-mcp-server/dist/index.js

Opción 2 — Config JSON (Claude Desktop / Claude Code)

En el archivo de config de MCP:

{
  "mcpServers": {
    "ordis": {
      "command": "node",
      "args": ["/ruta/absoluta/ordis-mcp-server/dist/index.js"],
      "env": {
        "ORDIS_API_KEY": "ordis_sk_TU_TOKEN"
      }
    }
  }
}

Usa la ruta absoluta a dist/index.js. Reinicia el cliente para que detecte el servidor.

Variables de entorno

Variable	Requerida	Descripción
ORDIS_API_KEY	Sí	Token de solo lectura (ordis_sk_...).
ORDIS_API_BASE_URL	No	Sobrescribe el base URL. Default: https://ordis.cl/api/v1.

Tools disponibles (11, todas solo lectura)

Tool	Endpoint	Parámetros
ordis_get_empresa	/me	—
ordis_list_facturas	/facturas	periodo?, tipo?, page?
ordis_get_f29	/f29	periodo?
ordis_get_f22	/f22	anio?
ordis_get_flujo_caja	/flujo-caja	anio?
ordis_get_kpis	/kpis	periodo?
ordis_list_liquidaciones	/liquidaciones	periodo?
ordis_list_trabajadores	/trabajadores	estado?
ordis_list_deudas	/deudas	estado?
ordis_list_movimientos_banco	/movimientos-banco	periodo?, page?
ordis_list_boletas_honorarios	/boletas-honorarios	periodo?, estado?, page?

• periodo valida el formato YYYY-MM en el cliente (falla rápido sin gastar una llamada de red).
• anio valida el rango 2020–2027.
• page debe ser ≥ 1.
• Enums validados en el cliente (mismos valores que la API): tipo = emitida | recibida · estado de boletas = vigente | anulada | rechazada · estado de deudas = activo | pagado | cancelado · estado de trabajadores = activo | licencia | vacaciones | desvinculado.
• En los endpoints con tope de filas (deudas, trabajadores), si la respuesta trae meta.has_more: true hay más datos que los devueltos.

Estructura

ordis-mcp-server/
├── package.json
├── tsconfig.json
├── README.md
└── src/
    ├── index.ts       # arranque + transporte stdio
    ├── client.ts      # cliente HTTP: auth por header, timeout, errores accionables
    ├── tools.ts       # registro de las 11 tools
    ├── schemas.ts     # campos Zod reutilizables (periodo, anio, page, estado)
    └── constants.ts   # base URL, timeout, límite de caracteres

Nota sobre versiones del SDK

Este servidor usa el SDK v1 (@modelcontextprotocol/sdk), que es la línea compatible y probada con la config stdio actual de Claude Code / Desktop.

Existe una línea v2 (@modelcontextprotocol/server, spec 2026-07-28) con paquetes renombrados y zod/v4. Cuando v2 se estabilice en los hosts, la migración es acotada: cambiar los imports, pasar inputSchema como z.object({...}) en vez de shape plano, y actualizar el transporte. La lógica de negocio (client.ts, mapeo de params) no cambia.

Seguridad

• Solo lectura: no hay tools que escriban, borren ni muten datos (la API de Ordis tampoco tiene endpoints de escritura).
• El token vive solo en la variable de entorno; nunca se loguea ni se persiste.
• En stdio, stdout es el canal del protocolo MCP: todos los logs van a stderr.
• Puedes revocar el token cuando quieras desde ordis.cl/portal/api-keys; el corte es inmediato. Rota el token si sospechas que se expuso.
• Al reportar un issue en este repositorio, no pegues respuestas de la API (contienen datos de tu empresa). Describe el error y el endpoint; con eso alcanza.