HVAC MCP Server for AI Agents

Microsoft Copilot Studio

Open your agent's Tools → Add a tool → New tool → Model Context Protocol.
Name the server VentilatePro HVAC and enter https://ventilatepro.com/mcp. Use Streamable HTTP.
Choose OAuth 2.0 → Dynamic discovery, create the tool, then select Create a new connection. Copilot discovers and registers its client automatically.
Sign in to VentilatePro, review the requested permissions and return address, and approve the connection. Add it to your agent.
Verify MCP initialization and tool discovery, then call vp_calculate_psychrometrics with {"dry_bulb":75,"relative_humidity":50,"units":"ip"}. Check for errors and confirm a returned dry bulb of 75 °F.

Registration uses /oauth/register; the legacy POST /register fallback also works. Before first sign-in, the operator must configure the exact Microsoft callback in MCP_OAUTH_EXTRA_REDIRECT_URIS. If the saved connector does not display it, temporarily enable MCP_OAUTH_REGISTRATION_DIAGNOSTICS=true and retry: the server records method, path, and sanitized callback URIs while rejecting unapproved callbacks with 400 JSON. Verify and configure the observed URI, disable diagnostics, restart the application, and retry. Do not guess a callback or allow wildcard Microsoft domains. Authorization and code exchange must match the client's full registered callback exactly.

All OAuth clients require S256 PKCE. The server supports public clients and registered client secrets with Basic or POST authentication. If scopes are requested explicitly, use advertised scopes such as projects:read calc:read calc:run. Refresh uses /oauth/token; do not add OpenID scopes.

Alternative: personal CLI token

Create a separate token in VentilatePro Account Settings with the smallest suitable permissions. In Copilot select API key → Header, set the header name to Authorization, and enter Bearer <CLI_TOKEN> as the connection credential value, including the prefix. Do not select Query or put a token in a URL, agent instructions, prompts, or tool arguments. The connection acts as the token owner and keeps existing project permissions, scopes, revocation, and confirmation guards. Personal tokens do not refresh automatically.

If an older connector retains discovery settings, recreate its failed connection/tool after deployment. Connector creation alone is not proof of a working connection: complete initialization, tool discovery, and the harmless calculation from Copilot. See Microsoft's MCP setup instructions.

ChatGPT Web

Connect an AI agent with OAuth—no token copying

VentilatePro exposes a public streamable-HTTP MCP server at https://ventilatepro.com/mcp. ChatGPT discovers VentilatePro's OAuth 2.1 metadata, opens the normal VentilatePro sign-in and consent screen, and sends short-lived scoped access tokens. Your password and refresh token are never exposed to the model.

1. Enable ChatGPT developer mode
In ChatGPT Settings, open Security and login and enable Developer mode. Workspace policy can control whether this option is available.
2. Create a custom plugin
Open ChatGPT Plugins, select the plus button, name it VentilatePro HVAC, choose Server URL, and enter the complete endpoint:
https://ventilatepro.com/mcp
3. Select OAuth
ChatGPT reads the protected-resource and authorization-server discovery documents automatically. No client secret, API key, or advanced override is required.
4. Sign in and approve
VentilatePro shows every requested scope before issuing the connection. OAuth uses authorization code + S256 PKCE, one-time codes, one-hour access tokens, rotating refresh tokens, and exact ChatGPT callback validation.
5. Review the tools
Confirm that ChatGPT discovers the VentilatePro tool catalog, then add the connection to a new chat from the tools menu. Guarded operations retain their explicit confirmation checks; ordinary create and update tools may write immediately. Review the tool schema before calling it.

Client menus and availability can change. See the official ChatGPT connection instructions for current account and workspace requirements.

Local Agent Quick Start

Connect a local agent in five steps

The PyPI package installs both the human-facing ventilatepro command and the local stdio server ventilatepro-mcp. The MCP server reuses the CLI login stored on the workstation; the token does not belong in the agent configuration.

1. Install or update the package pipx install ventilatepro-cli pipx upgrade ventilatepro-cli
2. Choose a token for project tools
Offline calculation tools need no token. For project work, choose the smallest suitable preset in Account Settings; Agent Editor covers the full workflow. Create the token and copy the raw value when it is shown. Use a separate token per workstation or agent host so it can be revoked independently.
Open Account Settings
3. Log in locally
Run the login command yourself and paste the token into the hidden prompt. Do not place the token in an MCP JSON file, repository, or agent prompt.
ventilatepro auth login
4. Run the agent health check
Doctor checks the full Agent Editor setup: saved login, required scopes, catalog, and identity. It can report failure for a deliberately narrower token or an offline-only installation. For offline use, verify vp_list_hvac_calculations and a calculation tool directly in your client.
ventilatepro mcp doctor
5. Register the MCP server codex mcp add ventilatepro -- ventilatepro-mcp
Restart or reconnect the MCP client after registration if it does not discover the tools immediately.

Offline HVAC tools

Calculate locally without a token or network request

The local stdio server exposes the same tested calculator used by ventilatepro calc, so these tools do not authenticate or make a network request. The public ChatGPT transport requires OAuth for the MCP connection itself, including when ChatGPT invokes an otherwise offline calculation tool. Available tools include vp_calculate_psychrometrics, vp_calculate_sensible_load, vp_calculate_total_load, vp_calculate_air_process, vp_calculate_hydronic, vp_calculate_steam, vp_calculate_fan_power, vp_calculate_pump_power, vp_calculate_duct_size, and vp_calculate_lmtd.

Read the calculation reference

Other MCP Clients

JSON configuration

Claude Desktop and other JSON-configured MCP clients can launch the same stdio executable.

{
  "mcpServers": {
    "ventilatepro": {
      "command": "ventilatepro-mcp",
      "args": []
    }
  }
}

If the client cannot find the executable, run where.exe ventilatepro-mcp on Windows or which ventilatepro-mcp on macOS/Linux and use that full path as command.

Guardrails

Agent access stays scoped

Tokens never bypass project membership or the web app's user permissions.
Read and write scopes are checked again by the server for every request.
ChatGPT OAuth access tokens expire after one hour; refresh tokens rotate on every use and can be revoked server-side.
Broad, destructive, import, export, apply, and run operations require an explicit confirm=true MCP argument.
Revit import confirmation also requires the unchanged review_token returned by a fresh read-only review.
Generic MCP request/workflow tools cannot commit or discard Revit imports; agents must use the specialized guarded tools.
Room categorization applies are stale-checked against current Revit identities and require reviewed reasons.
Meeting recording is atomic and idempotent; invalid assignees reject the entire batch.
Revoke a lost or unused token from Account Settings. CLI logout only clears the local copy.

Agent Workflows

Useful first operations

Revit import review

Inspect staged room and zone changes, conflicts, and options before approving the exact reviewed revision.

ventilatepro revit-imports review --project 123 --json

Room equipment

Inspect rooms with modeled plumbing, hydronic, environmental, and informational heat-gain requirements.

ventilatepro room-equipment summary --project 123

Room categorization

Export a guarded review artifact, make explicit engineering decisions, and apply only confirmed non-stale rows.

ventilatepro categorization review --project 123 --output room-categorization.json

Meeting capture

Resolve project members, record structured minutes, and create assigned project tasks in one transaction.

ventilatepro meetings context --project 123 --json

Discover MCP tools and their current schemas

MCP lets an AI client discover callable tools and their typed arguments. After connecting, use the client's tool listing (tools/list) as the authority for the installed server. Tool availability and permission to execute a tool are separate: appearing in the catalog does not grant access to a project.

Purpose	Tool	First input or next step
Offline calculator catalog	`vp_list_hvac_calculations`	`{}`; inspect formulas and required inputs.
Moist-air properties	`vp_calculate_psychrometrics`	`{"dry_bulb": 75, "relative_humidity": 50, "units": "ip"}`; dry bulb is °F and RH is percent.
Identity and granted scopes	`vp_whoami`	`{}`; requires project-tool authentication.
Supported workflows	`vp_describe_capabilities`	`{}`; also attempts to fetch server API schema metadata.
Request schema	`vp_get_schema`	`{"schema_key": "api_request"}`; inspect before composing a generic request.
Project discovery	`vp_list_projects`	`{"limit": 20, "offset": 0}`; select the returned project ID.
Review a staged Revit import	`vp_review_revit_import`	Pass the actual `project_id`; inspect the returned changes and review token.
Commit the reviewed import	`vp_confirm_revit_import`	Requires `project_id`, `import_id`, the unchanged `review_token`, and `confirm: true`.

Resources include ventilatepro://auth/me, ventilatepro://projects, and project templates such as ventilatepro://projects/{project_id}/hierarchy. These are MCP resource URIs, not browser URLs. Discover resources and templates through the client; project resources require authentication.

Run an inspectable engineering workflow

Discover tools, verify identity and scopes, then list projects. Resolve IDs from returned records instead of guessing names or using example IDs.
Read the relevant rooms, AHUs, calculation status, or pending import. Fetch every page when reviewing an entire schedule.
Present the inputs, units, calculation basis, affected records, and proposed changes. Preserve user overrides and explain assumptions.
Use the specialized write tool and its schema. Supply confirmation only for an authorized operation. A confirm argument is a programmatic guard, not proof that a person approved the change. Some ordinary create/update tools write without that argument.
If the review becomes stale, fetch a new review and compare changes again. Do not reuse an old import token or route around the specialized tool.
Read back changed records and report results, unresolved issues, and calculation freshness. A successful write does not by itself prove engineering adequacy.

Example first prompt: “Use VentilatePro to list my projects and let me identify the target. Read its rooms and calculation status, then report missing inputs and stale results with record IDs. Keep this review read-only.”

Example calculator prompt: “Use VentilatePro psychrometrics for 75 °F dry bulb and 50% RH at sea level. Report wet bulb, dew point, humidity ratio, enthalpy, pressure, and units. Explain the pressure assumption.”

Understand transport and tool errors

The local ventilatepro-mcp process speaks MCP over stdin/stdout. Let the client launch it; an idle terminal is expected when no protocol messages arrive. Do not add banners or other text to its stdout. GUI clients may have a different PATH or OS credential context than your terminal.

The hosted https://ventilatepro.com/mcp endpoint expects an MCP client with OAuth or a personal CLI bearer token. Unauthenticated GET and POST return a discovery challenge; it is not an HTML documentation page. For Copilot's API-key alternative choose Header, name Authorization, and credential value Bearer <CLI_TOKEN>. Never put credentials in query parameters or agent instructions.

Check both the protocol result and the tool payload. A completed HTTP request can still contain a tool error. Inspect isError where supplied and any structured error object before interpreting the response as engineering data. See the recovery reference.