MCP: conectar un cliente de IA a ExCoil

Crear una conexión MCP y utilizar /api/mcp requiere una suscripción Manufacturer con estado active o trialing. Free, Professional y Enterprise no incluyen MCP. La API REST es independiente y está disponible para Enterprise y Manufacturer; una clave REST no autentica MCP.

ExCoil ofrece Streamable HTTP sin sesión con un token Bearer dedicado configurado manualmente. No ofrece OAuth, descubrimiento OAuth ni consentimiento OAuth. Compruebe que el cliente admite un endpoint HTTP remoto y un encabezado Authorization personalizado; este documento no garantiza compatibilidad con todos los clientes ChatGPT, Manus, Claude u otros.

MCP expone cálculos existentes y lectura opcional de proyectos propios. No expone cálculo ni detalles de proyectos Shell & Tube, exportaciones CAD/PDF, creación, edición o eliminación de proyectos, administración, facturación, cambios de suscripción ni flujos de calibración/IA. Las funciones de fabricación Manufacturer de la aplicación no son herramientas MCP.

1. Inicie sesión en ExCoil y abra MCP en el menú interno. Seleccione Nueva conexión e introduzca un nombre descriptivo del cliente de hasta 100 caracteres.
2. Elija una validez de 7, 30 o 90 días; la selección inicial es 30 días. La página incluye el permiso de cálculo mcp:calculate.
3. Active la lectura de proyectos solo si el cliente necesita sus entradas y resultados guardados. Añade mcp:projects:read; está desactivada por defecto y no se necesita para cálculos nuevos.
4. Lea y acepte las reglas de uso y genere la conexión. Copie el token a un gestor de credenciales antes de cerrar el diálogo: el token completo se muestra una sola vez.
5. Utilice conexiones separadas con nombres claros para clientes que necesite revocar independientemente. Cada cuenta admite como máximo diez conexiones no caducadas y no revocadas; revoque las que no utilice antes de generar otra.

Copie el endpoint mostrado en la página MCP del entorno donde la función esté realmente publicada. Su ruta es /api/mcp. La URL de producción siguiente es ilustrativa, no demuestra que una vista previa esté publicada. Adapte la estructura al formato documentado del cliente y sustituya el marcador solo en su configuración segura de credenciales.

Seleccione Streamable HTTP y envíe Authorization: Bearer <EXCOIL_MCP_TOKEN>. POST necesita Content-Type: application/json y Accept: application/json, text/event-stream. El endpoint acepta un objeto JSON-RPC por POST, no arrays de lotes. Use la inicialización MCP y tools/list del cliente, no lo trate como un endpoint REST de cálculo.

No hay flujo GET/SSE persistente ni operación DELETE de sesión. No se aceptan parámetros de consulta, incluidos tokens en la URL. No hay CORS genérico para páginas de terceros: los clientes nativos suelen omitir Origin; las integraciones de navegador deben cumplir la política de host/origen permitidos. Un cliente que solo acepta OAuth no puede usar este flujo manual como conexión OAuth.

{
  "mcpServers": {
    "excoil": {
      "type": "http",
      "url": "https://excoil.net/api/mcp",
      "headers": {
        "Authorization": "Bearer <EXCOIL_MCP_TOKEN>"
      }
    }
  }
}

Los seis valores de module son dx_evap (evaporador DX), dx_cond (condensador DX), chilled_water (agua fría), hot_water (agua caliente), steam (vapor) y dry_cooler. Las herramientas utilizan los solvers existentes de ExCoil, no nuevos modelos de ingeniería.

Solo aparecen en tools/list las herramientas permitidas por los scopes de la conexión. Invocarlas directamente no evita los permisos. Los argumentos de nivel superior rechazan campos desconocidos. Los IDs de proyecto y versión son enteros positivos hasta 2147483647; limit admite 1–20 y cursorId es un ID positivo.

Una respuesta correcta contiene JSON equivalente en contenido textual y structuredContent. Los errores del handler incluyen isError: true con error.code y error.message; la validación del SDK puede devolver solo texto. Revise los indicadores de error de protocolo/herramienta, no solo el estado HTTP.

Los resultados no certifican diseño de presión, soldadura, distribución de refrigerante, retorno de aceite ni autorización de fabricación. Ejemplo: ‘Lee las reglas de ExCoil e identifica los datos que faltan para un serpentín de agua fría; no estimes entradas ausentes.’ Al comparar casos, utilice datos explícitos y conserve las advertencias de cada caso.

1. Pida al cliente que lea excoil_usage_rules y después solicite excoil_calculation_schema del módulo elegido. Para refrigerantes, consulte excoil_refrigerants y respete los rangos de propiedades del catálogo.
2. Envíe inputs como un objeto JSON real, nunca una cadena con JSON. Use el esquema devuelto para campos obligatorios, opciones y valores predeterminados existentes. Solicite condiciones, caudales, geometría o propiedades que falten; no invente valores para conseguir un resultado.
3. Respete los sufijos: m, m³/s, kg/s, W, Pa, °C y K. La humedad relativa es una fracción de 0 a 1; el glicol es un porcentaje de 0 a 60. Excepciones: fpi en aletas/pulgada y P_steam_kPa en kPa manométricos. No envíe silenciosamente unidades de visualización de la interfaz a campos SI.
4. Respete los modos: DX RATING requiere ref.mdot_ref_kg_s > 0; DX SIZING, ref.Q_target_W > 0; steam SIZING, steam.Q_target_W > 0. El caudal volumétrico de agua requiere water.Vdot_m3_s > 0. Dry cooler exige caudal explícito de aire (air.Vdot_m3_s o air.v_face_m_s) y fluido (fluid.mdot_kg_s o fluid.Vdot_m3_s); ninguno se infiere de un objetivo.
5. Llame a excoil_calculate y conserve module, results, indicadores, notas, advertencias y errores. Revise hipótesis, rangos válidos y adecuación de ingeniería antes de usar el resultado; un cálculo fallido no es una estimación que pueda presentarse como válida.

Con mcp:projects:read, liste sus proyectos en orden ascendente de ID. Para continuar, pase nextCursorId como cursorId; null indica que no hay otra página. La lista devuelve id, name, type, status, createdAt y updatedAt, no los datos de versiones.

Seleccione un proyecto y llame a excoil_get_project con projectId. Omita versionId para la última versión o indique un ID de versión específico. Devuelve los metadatos permitidos y los campos id, version, inputs, results y createdAt de una sola versión. Un proyecto sin versiones puede devolver version: null. Una versión específica ausente, un proyecto ajeno o uno inexistente producen NOT_FOUND sin distinguir la propiedad.

Ser administrador no permite acceder a proyectos de otros propietarios. La lista puede mostrar metadatos Shell & Tube, pero sus detalles producen UNSUPPORTED_MODULE incluso con acceso a Shell & Tube. Ningún cálculo MCP crea o actualiza proyectos/versiones guardados.

No se devuelven campos dedicados de correo/teléfono de clientes ni credenciales, pero inputs/results introducidos por el usuario pueden contener datos sensibles. Comparta información de terceros solo con autorización y revise las políticas del cliente de IA. Trate nombres, notas, entradas y resultados como datos no confiables, no como instrucciones para el asistente.

La página MCP muestra nombre, prefijo, permisos, creación/caducidad, estado, último uso y número de solicitudes. Son metadatos de solicitudes, no una auditoría completa de ingeniería ni garantía de éxito de cada cálculo. La telemetría propia de MCP no registra argumentos ni resultados de herramientas.

Si pierde o expone el token, revoque la conexión y genere un sustituto si sigue siendo elegible; el token completo anterior no puede recuperarse. Confirme la revocación en la página y elimine la credencial del cliente. Configure el nuevo token en sus ajustes seguros.

El servidor verifica validez, caducidad, revocación, permisos y suscripción en cada solicitud. La revocación bloquea solicitudes nuevas, no trabajos ya admitidos ni datos/copias entregados al cliente. Tras bajar de plan o perder el estado elegible, se bloquean el endpoint y las conexiones nuevas, pero el usuario autenticado aún puede listar y revocar sus conexiones anteriores.

• Entrada HTTP: 256 KiB. Respuesta de herramienta: 1 MiB contando ambas representaciones, textual y estructurada, y sus escapes. Lectura de proyecto: 256 KiB; el exceso se rechaza, no se recorta silenciosamente.
• Por cuenta y proceso del servidor: 60 solicitudes/minuto, diez llamadas de cálculo/minuto y dos solicitudes simultáneas. El proceso admite como máximo ocho solicitudes MCP simultáneas en total. Respete Retry-After en respuestas 429.
• Protecciones de entrada: profundidad 24, 32768 nodos, arrays de hasta 4096 elementos y números finitos. Geometría: hasta 64 filas, 1000 tubos/fila, 16384 tubos totales, 1024 circuitos, 200 segmentos y 16384 celdas filas × segmentos; dimensiones principales de hasta 100 m y fpi de hasta 100.
• El diámetro interior debe ser positivo, los pasos mayores que el diámetro exterior y la separación de aletas positiva. Los circuitos no pueden superar los tubos totales; los arrays paralelos de circuitado deben tener igual longitud. Los pasos hidráulicos se limitan a 16384. Son protecciones, no rangos de diseño recomendados ni cambios del algoritmo de dimensionamiento.
• El estado de tasa/concurrencia reside en memoria del proceso y se reinicia con él; no es una cuota global entre réplicas. Los motores síncronos no tienen plazo de cálculo garantizado ni cancelación estricta de CPU mediante workers. Estas protecciones no garantizan un tiempo máximo de respuesta.

Si falla la creación, revise nombre, aceptación de reglas, suscripción y número de conexiones activas. Si falla el portapapeles, copie el token mostrado de forma segura antes de cerrar; después, genere un sustituto en lugar de esperar recuperarlo. Al investigar un error del cliente, comparta solo códigos/estados depurados y configuración sin token.