MCP: conectar um cliente de IA ao ExCoil

Criar uma conexão MCP e usar /api/mcp exige assinatura Manufacturer com status active ou trialing. Free, Professional e Enterprise não incluem MCP. A API REST é separada e está disponível para Enterprise e Manufacturer; uma chave REST não autentica no MCP.

O ExCoil oferece Streamable HTTP sem sessão, com token Bearer dedicado configurado manualmente. Não oferece OAuth, descoberta OAuth nem fluxo de consentimento OAuth. Confirme se seu cliente aceita um endpoint HTTP remoto e um cabeçalho Authorization personalizado; este guia não garante compatibilidade com todo cliente ChatGPT, Manus, Claude ou outro.

O MCP expõe cálculos existentes e leitura opcional de projetos próprios. Não expõe cálculo ou detalhes de projetos Shell & Tube, exportações CAD/PDF, criação, edição ou exclusão de projetos, administração, cobrança, mudanças de assinatura ou fluxos de calibração/IA. Os recursos fabris Manufacturer da aplicação não são ferramentas MCP.

1. Entre no ExCoil e abra MCP no menu interno. Escolha Nova conexão e informe um nome descritivo para o cliente, com até 100 caracteres.
2. Escolha validade de 7, 30 ou 90 dias; a seleção inicial é 30 dias. A página inclui a permissão de cálculo mcp:calculate.
3. Ative a leitura de projetos somente se o cliente precisar das entradas e resultados salvos. Isso acrescenta mcp:projects:read; a opção vem desativada e não é necessária para cálculos novos.
4. Leia e aceite as regras de uso e gere a conexão. Copie o token para um gerenciador de credenciais antes de fechar o diálogo: ele é exibido integralmente uma única vez.
5. Crie conexões separadas e identificáveis para clientes que precisem de revogação independente. Cada conta aceita no máximo dez conexões não expiradas e não revogadas; revogue as não utilizadas antes de gerar outra.

Copie o endpoint mostrado na página MCP do ambiente onde o recurso está efetivamente publicado. O caminho é /api/mcp. A URL de produção abaixo é ilustrativa, não comprova publicação de uma prévia. Adapte a estrutura ao formato documentado do cliente e substitua o placeholder somente nas configurações seguras de credenciais.

Selecione Streamable HTTP e envie Authorization: Bearer <EXCOIL_MCP_TOKEN>. POST precisa de Content-Type: application/json e Accept: application/json, text/event-stream. O endpoint aceita um objeto JSON-RPC por POST, não arrays em lote. Use a inicialização MCP e tools/list do cliente, em vez de tratar o endereço como endpoint REST de cálculo.

Não há fluxo GET/SSE persistente nem operação DELETE de sessão. Nenhum parâmetro de consulta é aceito, inclusive token na URL. Não há suporte CORS genérico para páginas de terceiros: clientes nativos normalmente omitem Origin; integrações de navegador precisam atender à política de host/origem permitidos. Um cliente exclusivamente OAuth não pode usar este fluxo manual como conexão OAuth.

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

Os seis valores de module são dx_evap (evaporador DX), dx_cond (condensador DX), chilled_water (água gelada), hot_water (água quente), steam (vapor) e dry_cooler. As ferramentas usam os solvers existentes do ExCoil, não novos modelos de engenharia.

Somente ferramentas autorizadas pelos escopos aparecem em tools/list. Chamá-las diretamente não contorna permissões. Argumentos de topo recusam campos desconhecidos. IDs de projeto e versão são inteiros positivos até 2147483647; limit aceita 1–20 e cursorId é um ID positivo.

O sucesso traz JSON equivalente no conteúdo textual e em structuredContent. Erros do handler trazem isError: true com error.code e error.message; erros de validação do SDK podem trazer apenas texto. Verifique indicadores de erro de protocolo/ferramenta, não somente o status HTTP.

Resultados não certificam projeto de pressão, soldagem, distribuição de refrigerante, retorno de óleo ou liberação fabril. Exemplo de pedido: ‘Leia as regras do ExCoil e identifique os dados faltantes para uma serpentina de água gelada; não estime entradas ausentes.’ Em comparações, use casos explicitamente fornecidos e preserve os avisos de cada um.

1. Peça ao cliente para ler excoil_usage_rules e depois solicitar excoil_calculation_schema do módulo escolhido. Em casos com refrigerante, consulte excoil_refrigerants e preserve as faixas de propriedades do catálogo.
2. Forneça inputs como objeto JSON real, nunca como string contendo JSON. Use o schema retornado para campos obrigatórios, opções e defaults existentes. Pergunte por condições, vazões, geometria ou propriedades ausentes; não invente valores para fazer o cálculo executar.
3. Siga os sufixos: m, m³/s, kg/s, W, Pa, °C e K. Umidade relativa é fração de 0 a 1; glicol é percentual de 0 a 60. Exceções: fpi em aletas/polegada e P_steam_kPa em kPa manométricos. Não envie silenciosamente unidades de exibição da interface para campos SI.
4. Respeite os requisitos de modo: DX RATING precisa de ref.mdot_ref_kg_s > 0; DX SIZING de ref.Q_target_W > 0; steam SIZING de steam.Q_target_W > 0. Vazão volumétrica de água precisa de water.Vdot_m3_s > 0. Dry cooler exige vazão explícita de ar (air.Vdot_m3_s ou air.v_face_m_s) e fluido (fluid.mdot_kg_s ou fluid.Vdot_m3_s); nenhuma é inferida de uma meta.
5. Chame excoil_calculate e preserve module, results, flags, notas, avisos e erros retornados. Revise premissas, faixas de validade e adequação de engenharia antes de usar o resultado; falha de cálculo não é estimativa a apresentar como sucesso.

Com mcp:projects:read, liste seus projetos em ordem crescente de ID. Para continuar, envie nextCursorId como cursorId; null indica fim da paginação. A lista contém id, name, type, status, createdAt e updatedAt, não os dados das versões.

Selecione um projeto e chame excoil_get_project com projectId. Omita versionId para a versão mais recente ou informe um ID de versão específico. A resposta contém metadados permitidos e id, version, inputs, results e createdAt de uma única versão. Projeto sem versões pode retornar version: null. Versão específica ausente, projeto alheio e projeto inexistente retornam NOT_FOUND sem distinguir propriedade.

O papel de administrador não permite acessar projetos de outros proprietários. Metadados Shell & Tube podem aparecer na lista, mas seus detalhes retornam UNSUPPORTED_MODULE mesmo com direito de acesso ao Shell & Tube. Nenhum cálculo MCP cria ou atualiza projeto/versão salvo.

Campos cadastrais de e-mail/telefone do cliente e credenciais não são retornados, mas inputs/results inseridos pelo usuário ainda podem conter informações sensíveis. Compartilhe dados de terceiros somente com autorização e confira a política de dados do cliente de IA. Nomes, notas, entradas e resultados de projetos são dados não confiáveis, nunca instruções para o assistente.

A página MCP mostra nome, prefixo, permissões, criação/expiração, status, último uso e contagem de requisições. São metadados de requisição, não auditoria completa de engenharia nem garantia de cálculo bem-sucedido em cada chamada. A telemetria própria do MCP não registra argumentos ou resultados de ferramentas.

Se perder ou expuser o token, revogue a conexão e gere outra se ainda elegível; o token completo antigo não pode ser recuperado. Confirme a revogação na página e remova a credencial do cliente. Configure o substituto no local seguro de credenciais do cliente.

O servidor verifica validade, expiração, revogação, permissões e assinatura a cada requisição. Revogar bloqueia novas requisições, não trabalho já admitido nem dados/cópias já entregues ao cliente. Após downgrade ou perda do status elegível, o endpoint e novas conexões ficam bloqueados, mas o usuário autenticado continua podendo listar e revogar as conexões antigas.

• Entrada HTTP: 256 KiB. Resposta de ferramenta: 1 MiB somando representações textual e estruturada e escaping. Leitura de projeto: 256 KiB; saída excessiva é recusada, não abreviada silenciosamente.
• Por conta e processo do servidor: 60 requisições/minuto, dez chamadas de cálculo/minuto e duas requisições concorrentes. Cada processo admite no máximo oito requisições MCP simultâneas no total. Respeite Retry-After em respostas 429.
• Proteções de entrada: profundidade 24, 32768 nós, arrays de até 4096 elementos e somente números finitos. Geometria: até 64 fileiras, 1000 tubos/fileira, 16384 tubos totais, 1024 circuitos, 200 segmentos e 16384 células fileiras × segmentos; dimensões principais até 100 m e fpi até 100.
• Diâmetro interno deve ser positivo, passos maiores que o diâmetro externo e espaçamento de aletas positivo. Circuitos não podem superar tubos totais; arrays paralelos de circuitagem devem ter comprimentos iguais. Passes limitados a 16384. São limites protetivos, não faixas recomendadas de projeto nem mudança no algoritmo de dimensionamento.
• Os limites de taxa/concorrência ficam na memória do processo e reiniciam com ele; não são quota global entre réplicas. Os motores síncronos não têm prazo de cálculo garantido nem cancelamento estrito de CPU em worker. As proteções não garantem tempo máximo de resposta.

Se a criação falhar, confira nome, aceite das regras, assinatura e número de conexões ativas. Se a cópia falhar, copie o token exibido com segurança antes de fechar; depois disso, gere um substituto em vez de esperar recuperação. Ao investigar erros do cliente, compartilhe somente códigos/status sanitizados e configuração sem token.