MCP de InterFuerza: referencia técnica

Qué es

El MCP de InterFuerza es un servidor MCP (Model Context Protocol) que expone el API v4 de InterFuerza a agentes de inteligencia artificial: Claude y cualquier otro cliente MCP. Permite hacer consultas en lenguaje natural sobre la información de una empresa, con el usuario y los permisos reales de InterFuerza.

La versión 1 es de solo lectura: no crea, no edita y no borra.

La diferencia con el API v4: el token del API v4 lleva la empresa y el alcance, pero no el usuario. En el MCP, cada sesión se liga a un usuario concreto mediante OAuth, y cada consulta se filtra con los permisos de ese usuario.

Si busca los pasos para conectar su IA, vea la guía MCP de InterFuerza: conecte su IA a su cuenta.

Endpoint y rutas

El servidor responde en https://api.interfuerza.com.

Ruta	Qué hace
POST /mcp	Endpoint MCP (JSON-RPC).
POST /mcp/c/<nombre>	El mismo endpoint, con un nombre que diferencia el conector.
GET y POST /mcp/authorize	Inicio de sesión y pantalla de consentimiento de OAuth.
POST /mcp/token	Emisión de tokens.
POST /mcp/register	Registro dinámico de clientes (DCR).
POST /mcp/revoke	Revocación de tokens.
GET /.well-known/oauth-protected-resource	Metadatos del recurso (RFC 9728).
GET /.well-known/oauth-authorization-server	Metadatos del servidor de autorización (RFC 8414).

Las variantes /mcp/c/<nombre> son el mismo servidor. Existen porque algunos clientes, como Claude, no admiten dos conectores con la misma URL. Así puede agregar un conector por empresa. El nombre admite hasta 40 caracteres: letras, números, - y _.

Transporte MCP

• Streamable HTTP, solo con peticiones POST JSON-RPC. No hay stream SSE: un GET devuelve 405.
• Versiones del protocolo soportadas: 2025-06-18, 2025-03-26 y 2024-11-05.
• Acepta lotes (batch) de JSON-RPC. Las notificaciones, que no llevan id, devuelven 202.
• Autenticación: encabezado Authorization: Bearer <access_token>.

Método	Respuesta
initialize	Información del servidor e instrucciones para el modelo.
ping	Vacía.
tools/list	Solo las herramientas que el usuario tiene permitidas en ese momento.
tools/call	Ejecuta la consulta.
resources/list, prompts/list	Vacía.

Autenticación y autorización

El MCP usa OAuth 2.1 con PKCE S256 obligatorio, registro dinámico de clientes (RFC 7591), metadatos según RFC 9728 y RFC 8414, y revocación según RFC 7009.

Flujo

1. Registro. El cliente se registra con DCR. Solo se aceptan clientes públicos con PKCE: token_endpoint_auth_method=none, sin secreto. Cada redirect_uri debe usar https:// o http://localhost.
2. Autorización. El usuario inicia sesión con su usuario y clave de InterFuerza. La pantalla de consentimiento muestra el selector de Empresa, si el usuario tiene varias, y la nota de Solo lectura. El servidor devuelve al redirect_uri un code de un solo uso, válido por 300 segundos, junto con state e iss.
3. Token. El cliente cambia el code y su code_verifier por un access_token, válido por 1 hora, y un refresh_token, válido por 30 días.
4. Renovación. El refresh_token rota en cada uso. Reusar un code o un refresh_token ya usado revoca toda la familia de tokens de esa autorización.

Permiso "Acceso a MCP"

Para usar el MCP, el usuario necesita el permiso Acceso a MCP (código CONF0009) en la empresa que va a conectar. Sin ese permiso no hay acceso.

El permiso se verifica en cada punto: en el inicio de sesión, donde filtra las empresas que se ofrecen; en el consentimiento; en el canje del code; en la renovación; y en cada llamada al MCP. Si un administrador le quita el permiso a un usuario, su siguiente consulta devuelve 401 y sus tokens se revocan al instante.

Los permisos se administran en la configuración de usuarios. Vea Configuración de Usuarios.

Tokens

Cada token se liga a una empresa, un usuario, el alcance ifx:read y el recurso para el que se emitió. Un token presentado en otro recurso devuelve 401. El servidor guarda los tokens con hash SHA-256, nunca en texto plano.

Herramientas

El MCP ofrece 41 herramientas, todas de lectura. Cada una corresponde a una consulta del API v4 y exige el permiso de InterFuerza de esa función. Todas están anotadas con readOnlyHint: true y destructiveHint: false.

Las herramientas siguen dos patrones:

• listar_* busca registros. La respuesta viene paginada, con 25 registros por página. Acepta page y filters, y devuelve el total en count.
• ver_* recibe un id y trae el detalle del registro, con sus líneas e impuestos.

CRM

Herramienta	Consulta
listar_clientes, ver_cliente	Clientes
listar_contactos	Contactos
listar_prospectos, ver_prospecto	Prospectos
listar_eventos, ver_evento	Eventos
historial_crm	Historial de actividad del CRM
listar_proyectos	Proyectos

Ventas

Herramienta	Consulta
listar_cotizaciones, ver_cotizacion	Cotizaciones
listar_facturas, ver_factura	Facturas
listar_notas_credito, ver_nota_credito	Notas de crédito
listar_cobros, ver_cobro	Cobros

Compras

Herramienta	Consulta
listar_proveedores, ver_proveedor	Proveedores
listar_compras, ver_compra	Compras
listar_ordenes_compra	Órdenes de compra
listar_notas_credito_proveedor, ver_nota_credito_proveedor	Notas de crédito de proveedores

Productos e inventario

Herramienta	Consulta
listar_productos	Productos
listar_productos_ensamblados	Productos ensamblados
listar_combos	Combos
listar_productos_tienda, listar_productos_tienda_con_existencia	Productos de la tienda virtual, con o sin existencia
listar_categorias, listar_categorias_tienda	Categorías de productos y de la tienda virtual
listar_marcas	Marcas
listar_bodegas	Bodegas
listar_listas_precios	Listas de precios
listar_impuestos	Impuestos
listar_transferencias	Transferencias de inventario
listar_ajustes_inventario	Ajustes de inventario

Contabilidad

Herramienta	Consulta
listar_cuentas_contables	Catálogo de cuentas
listar_cuentas_por_defecto	Cuentas por defecto
listar_diario_contable	Diario contable

Configuración

Herramienta	Consulta
listar_usuarios	Usuarios

Algunas acciones del API v4 no forman parte del MCP porque no son consultas de lectura simple.

Ejecución de una consulta

En cada tools/call, el servidor hace lo siguiente:

1. Verifica el alcance ifx:read, que el usuario siga ligado a la empresa y que tenga, en ese momento, el permiso de la herramienta.
2. Valida los argumentos contra el esquema de la herramienta: tipos, valores permitidos y campos de filters. Rechaza comillas, barras invertidas y caracteres nulos.
3. Ejecuta la consulta en un proceso aislado, con un tiempo máximo de 120 segundos y una sesión de base de datos de solo lectura.
4. Limita la respuesta a 120,000 caracteres.
5. Registra la llamada en la bitácora de auditoría: usuario, empresa, herramienta y resultado.

La lectura tiene una doble barrera. La barrera lógica: solo existen herramientas de consulta. La barrera física: la sesión de base de datos es de solo lectura, así que cualquier escritura falla.

Filtros

• Los filtros solo admiten comparaciones exactas: =, !=, >, <, >= y <=. No hay búsqueda parcial.
• Un rango se expresa con dos filtros sobre el mismo campo. Por ejemplo, una fecha mayor o igual al primer día del mes y menor o igual al último.
• Solo se puede filtrar por los campos que cada herramienta declara en su esquema.

Guía para el modelo

El servidor le entrega al modelo el contexto que necesita para consultar bien:

• Las instrucciones de initialize se arman en cada sesión con el usuario, la empresa, el país, la moneda y la fecha del día. Incluyen las reglas de uso y un mapa de preguntas frecuentes con la herramienta que las responde.
• La descripción de cada herramienta indica el orden de los resultados, los valores reales del campo Status con su significado, y ejemplos de filters.

Seguridad

• Tokens guardados con hash, PKCE obligatorio, códigos de un solo uso y rotación del refresh_token, con revocación de toda la familia si un token se reusa.
• Sesiones de base de datos de solo lectura, lista blanca de campos y tipos en los filtros, y rechazo de metacaracteres en los argumentos.
• Límites de frecuencia por IP y por usuario en el registro de clientes, el inicio de sesión y la emisión de tokens. Después de varios intentos fallidos de inicio de sesión, el acceso se bloquea por 15 minutos.
• Protección CSRF en cada petición de autorización. Las pantallas de OAuth llevan CSP y X-Frame-Options: DENY.
• Bitácora de auditoría de cada consulta.

Límites conocidos de la versión 1

• Solo lectura. No hay escrituras, por diseño.
• Permisos por módulo, no por registro. Un usuario con permiso para listar facturas ve todas las facturas de la empresa. No hay un filtro del tipo "solo las asignadas a mí".
• Orden de los listados. Los listados del API v4 no vienen ordenados por fecha descendente: en general salen del registro más antiguo al más reciente. La guía para el modelo lo compensa.
• Dependencia del API v4. El MCP usa los datos del API v4 y hereda sus particularidades.