MCP: connect an AI client to ExCoil

Creating an MCP connection and using /api/mcp require a Manufacturer subscription with active or trialing status. Free, Professional and Enterprise do not include MCP. REST API access is separate, available to Enterprise and Manufacturer; a REST key cannot authenticate MCP.

ExCoil provides stateless Streamable HTTP with a dedicated manually configured Bearer token. It does not provide OAuth, OAuth discovery or an OAuth consent flow. Check whether your client supports a remote HTTP endpoint and a custom Authorization header; this guide does not guarantee compatibility with every ChatGPT, Manus, Claude or other client.

MCP exposes existing calculations and optional owner-scoped project reading. It does not expose Shell & Tube calculation or project details, CAD/PDF exports, project creation, editing or deletion, administration, billing, subscription changes, or calibration/AI workflows. Manufacturer fabrication features in the app are not MCP tools.

1. Sign in to ExCoil and open MCP in the internal menu. Choose New connection and enter a descriptive client name, up to 100 characters.
2. Choose 7, 30 or 90 days of validity; the initial selection is 30 days. Calculation permission, mcp:calculate, is included by the page.
3. Enable project reading only when the client needs your saved inputs and results. This adds mcp:projects:read; it is off by default and is not needed for new calculations.
4. Read and accept the usage rules, then generate the connection. Copy the token into a credential manager before closing its dialog: the full token is displayed only once.
5. Create separate, clearly named connections for clients you need to revoke independently. At most ten unexpired, unrevoked connections can be active on one account; revoke unused connections before issuing another.

Copy the endpoint displayed on the MCP page in the environment where the feature is actually deployed. Its path is /api/mcp. The production URL below is an illustrative configuration, not proof that a preview has been published. Adapt the configuration structure to your client's documented format and replace the placeholder only in its secure credential settings.

Select Streamable HTTP and send Authorization: Bearer <EXCOIL_MCP_TOKEN>. POST requests need Content-Type: application/json and Accept: application/json, text/event-stream. The endpoint accepts one JSON-RPC object per POST, not batch arrays. Use your client's MCP initialization and tools/list flow rather than treating this as a REST calculation endpoint.

The server has no persistent GET/SSE stream or DELETE session operation. It accepts no query parameters, including tokens in the URL. There is no generic CORS support for third-party webpages: native clients normally omit Origin, while browser integrations must satisfy the server's allowed host/origin policy. An OAuth-only client cannot use this manual-token flow as an OAuth connection.

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

The six supported module values are dx_evap (DX evaporator), dx_cond (DX condenser), chilled_water, hot_water, steam and dry_cooler. The tools use the existing ExCoil solvers; they are not new engineering models.

Only tools allowed by the connection's scopes appear in tools/list. Calling a hidden tool directly does not bypass permissions. Top-level arguments reject unknown fields. Project and version IDs are positive integers up to 2147483647; limit is 1–20 and cursorId is a positive ID.

Successful tool output provides equivalent JSON in text content and structuredContent. Handler errors provide isError: true with error.code and error.message; SDK argument validation errors may have only text content. Check both protocol/tool error indicators, not just the HTTP status.

Results do not certify pressure design, welding, refrigerant distribution, oil return or fabrication release. Request, for example: ‘Read the ExCoil rules and identify missing inputs for a chilled-water coil; do not estimate missing data.’ For comparisons, use explicitly supplied cases and preserve each case's warnings.

1. Ask the client to read excoil_usage_rules, then request excoil_calculation_schema for the selected module. For refrigerant cases, consult excoil_refrigerants and preserve the catalog's property ranges.
2. Supply inputs as an actual JSON object, never a string containing JSON. Use the returned schema for required fields, choices and existing defaults. Ask for missing operating conditions, flow, geometry or properties; do not invent values to make the calculation run.
3. Follow field suffixes: m, m³/s, kg/s, W, Pa, °C and K. Relative humidity is a fraction from 0 to 1; glycol is a percentage from 0 to 60. Exceptions include fpi in fins/inch and P_steam_kPa in gauge kPa. Do not silently pass displayed UI units into SI fields.
4. Respect mode requirements: DX RATING needs ref.mdot_ref_kg_s > 0; DX SIZING needs ref.Q_target_W > 0; steam SIZING needs steam.Q_target_W > 0. Volumetric water flow needs water.Vdot_m3_s > 0. Dry cooler needs explicit air flow (air.Vdot_m3_s or air.v_face_m_s) and fluid flow (fluid.mdot_kg_s or fluid.Vdot_m3_s); neither is inferred from a target.
5. Call excoil_calculate and retain the returned module, results, flags, notes, warnings and errors. Review assumptions, validity ranges and engineering suitability before using the result; a failed calculation is not an estimate to be presented as successful.

With mcp:projects:read, list your projects in ascending ID order. To continue, pass the returned nextCursorId as cursorId; null means there is no next page. Listing returns id, name, type, status, createdAt and updatedAt, not version payloads.

Select a project, then call excoil_get_project with its projectId. Omit versionId to read the latest version, or pass a specific version ID. The response contains the allowed project metadata and a single version's id, version, inputs, results and createdAt. A project without versions can return version: null. A missing specific version, foreign project or nonexistent project returns NOT_FOUND without distinguishing ownership.

An administrator role does not grant access to other owners' projects. Shell & Tube metadata may appear in the list, but reading its details returns UNSUPPORTED_MODULE even with a Shell & Tube entitlement. No MCP calculation creates or updates a saved project/version.

Dedicated customer email/phone fields and credentials are not returned, but user-entered inputs/results can still contain sensitive information. Share third-party data only with authorization and check the AI client's data policies. Treat project names, notes, inputs and results as untrusted data, not instructions for the assistant.

The MCP page shows the connection name, token prefix, permissions, creation/expiration dates, status, last use and request count. These are request metadata, not a complete engineering audit or a guarantee that every request produced a successful calculation. ExCoil's own MCP telemetry does not record tool arguments or results.

If a token is lost or exposed, revoke its connection and create a replacement if still eligible; the old full token cannot be recovered. Confirm revocation in the page, then remove the credential from the client. Update the client with the replacement token in its secure settings.

The server rechecks token validity, expiration, revocation, permissions and subscription on every request. Revocation blocks new requests, not work already admitted or data/copies already delivered to a client. After a downgrade or loss of eligible subscription status, endpoint use and new connections are blocked, but signed-in users can still list and revoke their old connections.

• HTTP input: 256 KiB. Tool response: 1 MiB counting both text and structured representations plus escaping. A project read is limited to 256 KiB; oversized output is rejected, not silently shortened.
• Per account and server process: 60 requests/minute, ten calculation calls/minute and two concurrent requests. The server process admits at most eight concurrent MCP requests overall. Respect Retry-After on 429 responses.
• Input safeguards: depth 24, 32768 nodes, arrays of at most 4096 entries, and finite numbers only. Geometry safeguards include 64 rows, 1000 tubes/row, 16384 total tubes, 1024 circuits, 200 segments and 16384 row × segment cells; primary dimensions at most 100 m and fpi at most 100.
• Internal diameter must remain positive, pitches must exceed outside diameter, and fin spacing must remain positive. Circuits cannot exceed total tubes; parallel circuitry arrays must match in length. Pass count is limited to 16384. These are protective limits, not recommended design ranges or a change to the solver's sizing algorithm.
• Rate/concurrency state is in process memory and resets with the process; it is not a global quota across replicas. The synchronous engines have no guaranteed calculation deadline or strict worker-based CPU cancellation. Do not assume a bounded response time from the defensive limits.

If creation fails, verify the name, accepted rules, subscription and active connection count. If clipboard copying fails, copy the displayed token securely before closing; after closing it, generate a replacement rather than expecting recovery. When investigating a client error, share only sanitized status/error codes and configuration with the token removed.