Saltar al contenido principal

MCP - Documentación de la API

El MCP de Koncili permite que la IA que ya usas para programar consulte la documentación de la API de Integración Financiera (ERP).

El MCP es exclusivo para clientes de Koncili. Para usar cualquiera de las herramientas necesitas una credencial válida de tu cuenta Koncili (la misma que se usa para autenticarse en la API de Integración Financiera — no es la cuenta que se usa para iniciar sesión en el sistema/panel de Koncili).

Requisitos previos:

  • Un cliente de IA compatible con MCP.
  • Tener un usuario y una contraseña con permiso de acceso a la API de Integración Financiera.

Cómo agregar el MCP a tu IA​

Hoy damos soporte oficial a las siguientes IAs: Claude Code, opencode, GitHub Copilot CLI, Claude Desktop/Web y ChatGPT Web.

Otros agentes compatibles con MCP vía HTTP pueden funcionar con la autenticación manual descrita más abajo.

Claude Code​

Esto es Claude Code, la CLI — no la extensión de VS Code

Las instrucciones siguientes son para Claude Code, la CLI oficial de Anthropic (instalación en code.claude.com/docs/es/quickstart). Puedes ejecutar los comandos siguientes en la terminal integrada de VS Code (o en cualquier otra terminal), pero Claude Code debe estar instalado antes — escribir los comandos en una terminal común, sin Claude Code instalado, no funcionará.

Requiere una cuenta paga de Anthropic

Claude Code no funciona con una cuenta gratuita. Se necesita un plan pago (Pro, Max, Team o Enterprise) o créditos de API en la Anthropic Console para usarlo.

1. Agrega el servidor MCP

En la terminal, dentro del proyecto donde quieres usar el MCP:

claude mcp add --transport http koncili-mcp-erp https://erp.koncili.com/mcp

Después de agregar el servidor, abre una nueva sesión de Claude Code (o reinicia la actual) para que el MCP aparezca disponible.

2. Inicia sesión

Puedes autenticarte de dos formas:

Opción A — desde el menú /mcp:

En Claude Code, escribe:

/mcp

Mostrará la lista de MCPs agregados. Selecciona koncili-mcp-erp con la tecla Enter y, a continuación, selecciona authenticate.

Opción B — con el comando directo:

claude mcp login koncili-mcp-erp

En ambos casos, Claude Code te lleva a la pantalla de inicio de sesión de Koncili. Según el ambiente:

  • Abre el navegador automáticamente;
  • Proporciona un enlace para que hagas clic. Si solo muestra el enlace, ábrelo en tu navegador, inicia sesión y avísale a Claude que ya completaste este paso.

Después de autorizar, Claude Code guarda la credencial y pasa a usarla en las siguientes preguntas. Si cierras la sesión, el inicio de sesión ocurre automáticamente en la primera pregunta que requiera el MCP.

Cuenta empresarial (Team/Enterprise)

Si el comando claude mcp add falla o el servidor no queda disponible por una política de la organización, pide al administrador/TI que habilite ese permiso o que agregue el servidor koncili-mcp-erp (misma URL anterior) en la configuración administrada. Si tienes dudas, envía un correo a erp@koncili.com.

Claude Desktop/Web​

1. Agrega el servidor MCP

En Claude Desktop o en Claude.ai (Web), ve a Configuración → Conectores → Agregar conector personalizado y completa:

  • Nombre: koncili-mcp-erp
  • URL: https://erp.koncili.com/mcp

2. Inicia sesión

En la primera pregunta que requiera el MCP o al hacer clic en Conectar, Claude abre automáticamente la pantalla de inicio de sesión de Koncili en el navegador. Después de entrar con correo y contraseña, la credencial queda guardada y pasa a usarse en las siguientes preguntas.

Cuenta empresarial (Team/Enterprise)

Si la opción de agregar un conector personalizado no aparece, o la conexión falla por una política de la organización, pide al administrador del workspace que habilite los conectores personalizados en la configuración de Claude para equipos/empresas.

opencode​

opencode lee la configuración de un archivo opencode.json (o opencode.jsonc, que acepta comentarios). Puedes crearlo en dos niveles:

  • Global (vale para todos los proyectos): ~/.config/opencode/opencode.json
  • Por proyecto: opencode.json en la raíz del repositorio
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "koncili-mcp-erp": {
      "type": "remote",
      "url": "https://erp.koncili.com/mcp",
      "enabled": true,
      "oauth": {}
    }
  }
}

El bloque "oauth": {} habilita el inicio de sesión automático: opencode detecta que el servidor exige una credencial y abre por sí solo el navegador en la pantalla de inicio de sesión de Koncili, en la primera pregunta que necesite el MCP.

Después de guardar el archivo de configuración, abre una nueva sesión de opencode (o reinicia la actual) para que el MCP aparezca disponible.

Si quieres disparar el inicio de sesión antes de preguntar algo, o verificar si ya estás autenticado:

opencode mcp auth koncili-mcp-erp

GitHub Copilot CLI​

1. Agrega el servidor MCP

copilot mcp add koncili-mcp-erp --transport http https://erp.koncili.com/mcp

Después de agregar el servidor, abre una nueva sesión de Copilot CLI (o reinicia la actual) para que el MCP aparezca disponible.

2. Haz la primera pregunta

En la primera pregunta que requiera el MCP, Copilot CLI abre automáticamente el navegador en la pantalla de inicio de sesión de Koncili.

Esto es la CLI, no la extensión de VS Code

Estas instrucciones valen para GitHub Copilot CLI y no para la extensión GitHub Copilot presente en diversos IDEs.

ChatGPT Web​

1. Agrega el servidor MCP

En ChatGPT (web), ve a Configuración → Plugins, haz clic en Explorar conectores/plugins y después en + para agregar un conector personalizado. Completa:

  • Nombre: koncili-mcp-erp
  • URL del MCP: https://erp.koncili.com/mcp
  • Autenticación: OAuth

2. Inicia sesión

Al usar el conector por primera vez en una conversación, ChatGPT abre automáticamente la pantalla de inicio de sesión de Koncili en el navegador. Después de entrar con correo y contraseña, la credencial queda guardada y pasa a usarse sola en las siguientes preguntas.

Cuenta corporativa (Team/Enterprise)

En las cuentas corporativas, los conectores personalizados pueden estar deshabilitados por defecto. Pide al administrador del workspace que habilite los conectores personalizados en la configuración de administración de ChatGPT.

Autenticación manual​

Si el inicio de sesión automático no funciona en tu ambiente, es posible autenticarse pegando un token manualmente:

1. Abre https://erp.koncili.com/mcp/login.html en el navegador y entra con el correo y la contraseña de tu cuenta Koncili.

2. Copia el token que aparece en la pantalla — la credencial vale por aproximadamente 2 horas.

3. Pega el token en el encabezado Authorization de la configuración de tu cliente:

{
  "mcpServers": {
    "koncili-mcp-erp": {
      "type": "http",
      "url": "https://erp.koncili.com/mcp",
      "headers": {
        "Authorization": "Bearer <TU_TOKEN>"
      }
    }
  }
}

Cuando el token expire, vuelve a la pantalla de inicio de sesión y genera uno nuevo.

Qué hace (y qué no hace)​

El servidor MCP de Koncili es una base de conocimiento — no es la API en sí.

  • ✅ Responde dudas sobre la integración: autenticación, configuración inicial (whitelist de IP, releasetype), catálogo de endpoints, errores comunes y ejemplos de solicitud.
  • ✅ Responde dudas de reglas de negocio: sobre movimientos, rutinas, etc.
  • ✅ Responde solo con lo que está documentado. Cuando no encuentra la respuesta en la base oficial, dice que no la encontró — y almacena la información con el fin de mejorar la base de conocimiento del MCP.
  • ❌ No ejecuta llamadas a la API de Koncili. No envía pedidos, no busca tus movimientos y no aplica cobros. Solo explica cómo hacerlo.
  • ❌ No accede a los datos de tu cuenta. Aunque exige inicio de sesión, el MCP solo consulta documentación y FAQ — no lee tus movimientos, conciliaciones ni liquidaciones. Esto se implementará en el futuro.

Herramientas (tools) disponibles​

Tu IA elige automáticamente cuál de estas herramientas usar según la pregunta — no necesitas llamarlas manualmente. Todas exigen la misma credencial.

HerramientaPara qué sirve
search_documentationBúsqueda en lenguaje natural en la documentación pública
list_endpointsLista el catálogo de endpoints de la integración ERP
detail_endpointMuestra la especificación completa de un endpoint (parámetros, schemas, errores)
list_common_errorsLista los errores de protocolo más comunes (p. ej.: token ausente, 403, 429, 412)
generate_request_exampleGenera un ejemplo de curl listo para un endpoint (con el token como placeholder)
search_faqBusca respuestas sobre reglas de negocio que no están en la documentación pública

Verificar la conexión​

Después de configurar, haz una prueba rápida pidiéndole a tu IA algo que solo la documentación de Koncili responde. Por ejemplo:

"Usando el MCP de Koncili, ¿por cuánto tiempo es válido el token de acceso?"

"Lista los endpoints de la API de Integración Financiera de Koncili."

Si la IA responde citando la documentación, la conexión está funcionando.

Si la respuesta es un error, el código ayuda a identificar la causa:

  • 401 — credencial ausente, inválida o expirada. Vuelve a iniciar sesión según tu IA.
  • 403 — la credencial es válida, pero tu cuenta no tiene habilitado el permiso necesario. Comunícate con erp@koncili.com.

Buenas prácticas y limitaciones​

  • Haz preguntas cortas y objetivas. Evita preguntas muy largas y varias preguntas al mismo tiempo; ve directo al punto para aumentar la precisión de la respuesta.
  • Incluye el contexto de Koncili en la pregunta. Siempre que sea posible, usa la palabra "Koncili" en el enunciado. Ejemplo: prefiere "¿Qué es un movimiento en Koncili?" en lugar de "¿Qué es un movimiento?" para evitar interpretaciones fuera del contexto de la integración.
  • Rate limit: el MCP acepta hasta 90 solicitudes por minuto.

Privacidad y tratamiento de datos​

El MCP de Koncili exige una credencial válida para cualquier pregunta, en cualquier herramienta:

  • Toda llamada queda asociada a tu cuenta. Como la credencial es obligatoria, almacenamos el identificador y el correo de la cuenta Koncili usados en la llamada, además de la fecha/hora y de qué herramienta se usó.

  • Las preguntas respondidas no se almacenan. Cuando la documentación o el FAQ responden a tu pregunta, el contenido de la pregunta no se graba. Con fines estadísticos, almacenamos el correo y la fecha de acceso para construir indicadores.

  • Las preguntas no respondidas se almacenan para mejorar la documentación y el FAQ. Cuando el MCP no encuentra una respuesta, guarda el texto de la pregunta, para que el equipo de Koncili haga evolucionar la base de conocimiento.

    Estos registros sirven para la curaduría de la documentación y el soporte a tu cuenta — no se usan para fines ajenos a la integración.

No envíes datos sensibles en las preguntas

Como el texto de las preguntas sin respuesta se almacena, no incluyas datos personales, tokens, credenciales ni información sensible en las preguntas hechas al MCP. Pregunta sobre la documentación — no pegues datos reales.

Al conectar y usar el MCP de Koncili con tu credencial, quedas informado de este tratamiento de datos. Dudas sobre privacidad: erp@koncili.com.

Soporte​

Dudas sobre la API de Integración Financiera (ERP), incluido el MCP: erp@koncili.com.