Servidor MCP (Model Context Protocol)

El estándar abierto para proveer herramientas financieras a la Inteligencia Artificial Agéntica.

¿Qué es MCP?

El Model Context Protocol (MCP) es un estándar universal que permite a los asistentes de Inteligencia Artificial conectarse a fuentes de datos seguras.

Al configurar el Servidor MCP de Cord, empoderas a agentes como Claude o asistentes integrados en IDEs (como Cursor) para interactuar orgánicamente con tu empresa.

Preguntas que puedes hacer a la IA una vez conectada:

• “Extrae del PDF adjunto los requerimientos y genera una cotización en Cord para este cliente.”
• “Revisa las cotizaciones vencidas de los últimos 30 días y redáctame correos de cobranza amigables.”
• “Busca al cliente Distribuidora El Zarco y arma un borrador con estas 3 líneas.”

Cómo configurar la conexión

La autenticación para tu cliente de IA se realiza utilizando tu Clave de API estándar de Cord (sk_live_… / sk_test_…) — la misma que usa la API REST.

1. Navega a Ajustes › Desarrolladores › MCP en la interfaz de Cord (aparece al activar el Modo desarrollador al final del índice de Ajustes).
2. Un tablero de estado arriba te dice si ya tienes una llave activa y, si ya conectaste un cliente de IA, cuándo se usó por última vez. Si no tienes ninguna, el botón “Crear llave para MCP” genera una llave write sin salir de la página — se pega sola en la configuración de abajo. Cópiala en ese momento: no se vuelve a mostrar. (También puedes crear una desde la pestaña API del Cord Workbench si prefieres controlar el scope a mano — write para las herramientas de escritura, read alcanza para las de lectura.)
3. Copia la configuración JSON del cliente MCP proporcionada en pantalla.
4. Pega esta configuración en la ruta local correspondiente a tu cliente (por ejemplo, el archivo claude_desktop_config.json si usas la aplicación Claude for Desktop).

Dos formas de conectarte

Streamable HTTP (recomendado) — POST https://cordhq.app/api/mcp con el header Authorization: Bearer sk_live_…. Sin sesión: cada mensaje JSON-RPC es una petición HTTP independiente. Es lo que espera la mayoría de los clientes MCP modernos.

HTTP + SSE (legacy, se mantiene para clientes antiguos) — GET https://cordhq.app/api/mcp/sse abre una conexión de larga duración y devuelve dónde mandar los mensajes (POST /api/mcp/message?sessionId=…). Cada mensaje POST debe llevar el mismo Authorization: Bearer con el que abriste la sesión — no basta con el sessionId de la URL (viaja en texto plano y puede quedar expuesto en logs de proxies intermedios), y la llave debe pertenecer a la misma organización que abrió la sesión.

Herramientas disponibles

Tool	Qué hace	Permiso
listar_cotizaciones	Lista cotizaciones, con filtro opcional por estado.	lectura
detalle_cotizacion	Detalle completo de una cotización: líneas, totales, línea de tiempo.	lectura
cartera_vencida	Cuentas por cobrar VENCIDAS: monto, aging, detalle por cliente.	lectura
resumen_negocio	KPIs, embudo de conversión, pronóstico de pipeline, uso del plan.	lectura
buscar_cliente	Busca en el directorio por empresa/contacto/RFC/correo. Paginado.	lectura
listar_productos	Catálogo de productos (id, SKU, nombre, unidad, precio de lista). Paginado.	lectura
crear_cotizacion_borrador	Crea una cotización en BORRADOR (no la envía). Idempotente si mandas idempotency_key.	escritura
listar_facturas	Lista las facturas de Cord Invoicing con su saldo y estado (draft|open|paid|void|uncollectible|overdue). Filtra por estado, cliente o texto libre. Paginado.	lectura
detalle_factura	Detalle completo de UNA factura: conceptos, emisor, receptor, impuestos, tipo de cambio declarado, saldo y pagos recibidos.	lectura
crear_factura_borrador	Crea una factura en BORRADOR para un cliente, sin necesidad de una cotización previa. Requiere el plan Starter o superior (Cord Invoicing).	escritura
enviar_cotizacion	Envía al cliente una cotización en borrador (correo con el link). En el plan Gratis consume un envío del mes.	escritura
aprobar_cotizacion	Marca como aprobada una cotización enviada o vista.	escritura
rechazar_cotizacion	Marca como rechazada una cotización enviada o vista.	escritura
registrar_pago_cotizacion	Registra que una cotización aprobada se pagó por fuera de Cord y cancela sus cobros en línea pendientes. Acepta metodo_pago.	escritura
crear_cliente	Da de alta un cliente (empresa, contacto, correo, teléfono, identificador fiscal, términos, país).	escritura
actualizar_cliente	Cambia datos de contacto de un cliente. Solo modifica lo que mandas; nunca toca crédito, nivel ni descuento.	escritura
crear_tarea	Crea una tarea de seguimiento, opcionalmente ligada a una cotización y con fecha.	escritura
registrar_promesa_pago	Registra la fecha en que el cliente prometió pagar una cotización. No cobra nada.	escritura
listar_eventos	Historial del negocio (cotizaciones, facturas, clientes, tareas, promesas), filtrable por tipo u objeto. Paginado.	lectura

Cada tool declara sus anotaciones estándar de MCP (readOnlyHint, idempotentHint, destructiveHint) en tools/list — un cliente MCP puede usarlas para decidir qué llamadas auto-aprobar sin preguntarle al usuario cada vez. Las de lectura son readOnlyHint: true. enviar_cotizacion, aprobar_cotizacion, rechazar_cotizacion y registrar_pago_cotizacion son destructiveHint: true porque cambian el estado de una cotización o le escriben al cliente: un cliente MCP bien configurado pide confirmación antes de ejecutarlas. Ninguna herramienta emite ni timbra facturas: eso sigue siendo una acción que una persona dispara desde la app o la API.

Paginación

listar_cotizaciones, buscar_cliente, listar_productos, listar_facturas y listar_eventos devuelven páginas, no la tabla completa:

{
  "items": [ { "id": "…", "empresa": "Distribuidora El Zarco" } ],
  "total": 47,
  "has_more": true,
  "next_cursor": "20"
}

Si has_more viene en true, vuelve a llamar la misma tool pasando cursor: next_cursor para la siguiente página. next_cursor viene en null cuando ya no hay más resultados. listar_cotizaciones devuelve la lista en cotizaciones y listar_eventos en eventos.

Llamadas seguras de repetir (idempotencia)

crear_cotizacion_borrador, enviar_cotizacion, aprobar_cotizacion, rechazar_cotizacion, registrar_pago_cotizacion, crear_cliente, crear_tarea y registrar_promesa_pago aceptan un idempotency_key opcional — un identificador único que tú generas (un UUID, por ejemplo). Si tu cliente MCP necesita reintentar la llamada porque no recibió respuesta a tiempo (timeout de red), repite el MISMO idempotency_key: Cord te devuelve el resultado de la primera vez en vez de repetir la acción. Reusar la misma clave con otros argumentos devuelve un error, y la clave caduca a las 24 horas.

{
  "name": "crear_cotizacion_borrador",
  "arguments": {
    "idempotency_key": "a1b2c3d4-…",
    "cliente_id": "…",
    "items": [{ "descripcion": "Instalación", "cantidad": 1, "precio_unitario": 4500 }]
  }
}

Sin idempotency_key, la tool sigue funcionando normal — cada llamada crea un borrador nuevo (no es un campo obligatorio, solo recomendado si tu cliente reintenta automáticamente).

Herramientas Seguras (Tools)

Cord expone de forma controlada “Herramientas” (Tools) hacia la IA. Esto significa que la IA no tiene acceso crudo e ilimitado a tu base de datos; la IA únicamente puede invocar los endpoints que Cord ha aprobado y categorizado, heredando los permisos vinculados a la Clave de API.

Límites, medición y actividad

Cada llamada real (no las notificaciones de protocolo como notifications/initialized) cuenta igual que una llamada a la API REST: contra tu cuota de uso del plan, contra el límite de peticiones por llave (600/min), y queda en la pestaña Registros del Cord Workbench con la tool que se llamó (ej. /mcp/tools/call:listar_productos) — así puedes ver exactamente qué está haciendo tu agente, con qué llave y cuándo. Puedes filtrar ese log por método o por status, o buscar mcp en la ruta para aislar solo lo que hizo la IA.