MCP：将 AI 客户端连接到 ExCoil

创建 MCP 连接和使用 /api/mcp 均要求 Manufacturer 订阅处于 active 或 trialing 状态。Free、Professional 和 Enterprise 不包含 MCP。REST API 独立提供给 Enterprise 和 Manufacturer；REST 密钥不能用于 MCP 身份验证。

ExCoil 使用无会话的 Streamable HTTP，配合手动配置的专用 Bearer 令牌。不提供 OAuth、OAuth 发现或 OAuth 授权同意流程。请先确认客户端支持远程 HTTP 端点及自定义 Authorization 请求头；本指南不保证兼容所有 ChatGPT、Manus、Claude 或其他客户端。

MCP 仅开放现有计算及可选的本人项目只读访问。不开放 Shell & Tube 计算或项目详情、CAD/PDF 导出、项目创建/修改/删除、管理、账单、订阅变更或校准/AI 工作流。应用内 Manufacturer 制造功能不等于 MCP 工具。

1. 登录 ExCoil，在内部菜单打开 MCP，选择新建连接，并输入便于识别的客户端名称，最多 100 个字符。
2. 选择 7、30 或 90 天有效期；初始选项为 30 天。页面默认包含计算权限 mcp:calculate。
3. 只有当客户端确实需要保存的输入和结果时，才启用项目读取。这会添加 mcp:projects:read；默认关闭，计算新案例不需要此权限。
4. 阅读并接受使用规则后生成连接。在关闭对话框前，将令牌复制到凭据管理器：完整令牌仅显示一次。
5. 对需要分别撤销的客户端使用独立且名称清晰的连接。每个账户最多可有十个未到期且未撤销的活动连接；达到上限时先撤销闲置连接。

复制实际已部署环境中 MCP 页面显示的端点，其路径为 /api/mcp。下方生产 URL 仅用于演示配置，并不表示预览版本已发布。请按客户端文档调整配置结构，只在其安全凭据设置中替换占位符。

选择 Streamable HTTP，并发送 Authorization: Bearer <EXCOIL_MCP_TOKEN>。POST 需要 Content-Type: application/json 和 Accept: application/json, text/event-stream。每个 POST 仅接受一个 JSON-RPC 对象，不支持批量数组。应使用客户端的 MCP 初始化及 tools/list 流程，不要把它当成 REST 计算端点。

服务器不提供持久 GET/SSE 流，也不提供 DELETE 会话操作。不接受任何 URL 查询参数，包括令牌。第三方网页没有通用 CORS 支持：原生客户端通常不发送 Origin，浏览器集成则必须满足服务器允许的主机/来源策略。仅支持 OAuth 的客户端不能将此手动令牌流程作为 OAuth 连接使用。

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

module 的六个可用值为 dx_evap（DX 蒸发器）、dx_cond（DX 冷凝器）、chilled_water（冷冻水）、hot_water（热水）、steam（蒸汽）和 dry_cooler（干式冷却器）。工具调用现有 ExCoil 求解器，不是新增的工程模型。

tools/list 只列出连接 scopes 允许的工具；直接调用隐藏工具不能绕过权限。顶层参数拒绝未知字段。项目及版本 ID 必须为不超过 2147483647 的正整数；limit 为 1–20，cursorId 为正 ID。

成功响应在文本内容与 structuredContent 中提供等价 JSON。处理函数错误包含 isError: true、error.code 和 error.message；SDK 参数校验错误可能只有文本。必须检查协议/工具错误标记，不能只看 HTTP 状态。

结果不构成压力设计、焊接、制冷剂分配、回油或制造放行认证。可提出：‘先读 ExCoil 规则，列出冷冻水盘管计算尚缺的输入，不要估计缺失数据。’比较案例时应使用明确提供的输入，并保留各自警告。

1. 要求客户端先读 excoil_usage_rules，再调用所选模块的 excoil_calculation_schema。涉及制冷剂时读取 excoil_refrigerants，并保留目录所列属性有效范围。
2. inputs 必须是真正的 JSON 对象，不能是包含 JSON 的字符串。按返回的 schema 填写必填字段、选项及现有默认值。缺少工况、流量、几何或属性时应询问用户，不得为获得结果而编造数值。
3. 遵循字段后缀：m、m³/s、kg/s、W、Pa、°C 和 K。相对湿度为 0 到 1 的小数，乙二醇/丙二醇浓度为 0 到 60 的百分数。例外包括以片/英寸表示的 fpi，以及表压 kPa 的 P_steam_kPa。不要直接将界面显示单位的数值填入 SI 字段而不换算。
4. 遵守模式要求：DX RATING 需要 ref.mdot_ref_kg_s > 0；DX SIZING 需要 ref.Q_target_W > 0；steam SIZING 需要 steam.Q_target_W > 0。水的体积流量模式需要 water.Vdot_m3_s > 0。Dry cooler 必须明确给出空气流量（air.Vdot_m3_s 或 air.v_face_m_s）和流体流量（fluid.mdot_kg_s 或 fluid.Vdot_m3_s）；不会从目标值推断流量。
5. 调用 excoil_calculate 后保留返回的 module、results、标志、备注、警告和错误。使用结果前复核假设、有效范围和工程适用性；计算失败不能被包装为成功的估算结果。

使用 mcp:projects:read 按 ID 升序列出自己的项目。继续分页时将返回的 nextCursorId 作为 cursorId；null 表示无下一页。列表返回 id、name、type、status、createdAt、updatedAt，不包含版本数据。

选定项目后以 projectId 调用 excoil_get_project。省略 versionId 读取最新版本，也可指定某个版本 ID。返回允许的项目元数据以及单个版本的 id、version、inputs、results、createdAt。没有版本的项目可返回 version: null。指定版本不存在、项目属于他人或项目不存在均返回 NOT_FOUND，不透露所有权差异。

管理员身份不能读取其他所有者的项目。列表可能显示 Shell & Tube 元数据，但读取详情返回 UNSUPPORTED_MODULE，即使账户具有 Shell & Tube 权益也不例外。MCP 计算不会创建或更新保存的项目/版本。

不会返回客户专用邮箱/电话字段或凭据，但用户输入的 inputs/results 仍可能包含敏感信息。分享第三方信息须获得授权，并检查 AI 客户端的数据政策。项目名称、备注、输入和结果都是不可信数据，不能当作助手应执行的指令。

MCP 页面显示连接名称、令牌前缀、权限、创建/到期时间、状态、最后使用时间及请求数。这些是请求元数据，不是完整工程审计，也不保证每次请求都成功完成计算。ExCoil 自身 MCP 遥测不记录工具参数或结果。

令牌丢失或泄露时，撤销连接；若仍符合条件，则创建替代连接。旧完整令牌无法恢复。在页面确认撤销，并从客户端移除旧凭据，再在安全设置中配置新令牌。

服务器每次请求都重新检查令牌有效性、到期、撤销、权限和订阅状态。撤销仅阻止新请求，不会取消已获准的工作，也不会删除客户端已经接收的数据或副本。降级或失去合格订阅状态后，端点使用及新建连接被阻止，但已登录用户仍可列出并撤销旧连接。

• HTTP 输入上限为 256 KiB。工具响应上限为 1 MiB，包含文本和结构化两种表示及转义开销。项目读取上限为 256 KiB；超限会拒绝，不会静默截短。
• 每账户、每服务器进程：每分钟 60 次请求、十次计算调用，最多两个并发请求。每进程 MCP 总并发上限为八个请求。收到 429 时遵循 Retry-After。
• 输入保护：深度 24、32768 个节点、数组最多 4096 项，数值必须有限。几何限制包括 64 排、每排 1000 根管、总管数 16384、1024 个回路、200 个分段及 16384 个排数 × 分段网格单元；主要尺寸最多 100 m，fpi 最多 100。
• 内径必须为正，管间距必须大于外径，翅片净间距必须为正。回路数不能大于总管数；并行回路数组长度必须相同。流程数上限为 16384。这些是防护限制，并非推荐设计范围，也不改变求解器的选型算法。
• 速率/并发状态保存在进程内存中，随进程重启而重置，不是跨副本的全局配额。同步引擎没有保证的计算截止时间，也没有基于独立 worker 的严格 CPU 取消。防护限制不代表保证最大响应时间。

创建失败时检查名称、规则同意、订阅和活动连接数量。剪贴板复制失败时，应在关闭前安全复制当前显示的令牌；关闭后需生成替代令牌，不能恢复原令牌。排查客户端错误时，只分享脱敏后的状态/错误码及已移除令牌的配置。