# AI agents and MCP

Connect AI agents to VentilatePro using remote OAuth MCP or local stdio. Explore HVAC calculation tools, project schemas, and guarded Revit workflows.

Canonical: https://ventilatepro.com/exam/cli/mcp/

Documentation version: VentilatePro CLI 0.8.4

## VentilatePro in ChatGPT

Use the sidebar workspace for six HVAC calculators and saved project results. Follow the dedicated [ChatGPT setup and prompt guide](https://ventilatepro.com/exam/cli/chatgpt/). Its read-only endpoint is `https://ventilatepro.com/mcp/workspace`.

## Microsoft Copilot Studio

1. Open your agent's **Tools → Add a tool → New tool → Model Context Protocol**.
2. Name the server **VentilatePro HVAC** and enter `https://ventilatepro.com/mcp`. Use **Streamable HTTP**.
3. Choose **OAuth 2.0 → Dynamic discovery**, create the tool, then select **Create a new connection**. Copilot discovers and registers its client automatically.
4. Sign in to VentilatePro, review the requested permissions and return address, and approve the connection. Add it to your agent.
5. 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](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent).

## 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:

   ```text
   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](https://developers.openai.com/plugins/deploy/connect-chatgpt) for current account and workspace requirements.

## 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

   ```text
   pipx install ventilatepro-cli
   ```

   ```text
   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](https://ventilatepro.com/hvac/?view=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.

   ```text
   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.

   ```text
   ventilatepro mcp doctor
   ```
5. Register the MCP server

   ```text
   codex mcp add ventilatepro -- ventilatepro-mcp
   ```

   Restart or reconnect the MCP client after registration if it does not discover the tools immediately.

## 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](https://ventilatepro.com/exam/cli/calculations/#calculation-mcp)

## JSON configuration

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

```text
{
  "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`.

## 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.

## Agents follow the memory playbook

Each project shares its current code edition, applicable HCAI/OSHPD facility type, scope of work, notes, decisions, and tasks with agents.
Add or edit the scope of work in Project Settings; it is saved in project memory and included in
`vp_memory_context` and `vp_memory_search`. Agents can also update it with
`vp_update_project` using `scope_of_work`; an empty string clears it.
Before an agent writes notes, decisions, or tasks, the
conversation loads the memory playbook: how to search, what to save, how to log a session, and how to tidy memory.
`vp_memory_context` loads it at the start of work on a project; an agent that skips it is asked to load it on its
first write. It works in every MCP client with no setup.

### Optional: install the skill

Clients that support Agent Skills (Claude, Claude Code) can install the same playbook so it is at hand before the first call. Upload the zip as a skill, or unzip it into `~/.claude/skills/`.

[Download ventilatepro-memory.zip](https://ventilatepro.com/api/notes/memory/playbook/skill.zip)

### Optional: add to your instructions

Paste into a Claude project, ChatGPT custom instructions, or `CLAUDE.md`:

```text
When working on a VentilatePro project, call vp_memory_context first and follow the memory playbook it returns. Search project memory before answering, and log the session with vp_log_session before finishing.
```

## Useful first operations

### Revit import review

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

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

### Room equipment

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

```text
ventilatepro room-equipment summary --project 123
```

### Room categorization

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

```text
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.

```text
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

1. Discover tools, verify identity and scopes, then list projects. Resolve IDs from returned records instead of guessing names or using example IDs.
2. Read the relevant rooms, AHUs, calculation status, or pending import. Fetch every page when reviewing an entire schedule.
3. Present the inputs, units, calculation basis, affected records, and proposed changes. Preserve user overrides and explain assumptions.
4. 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.
5. 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.
6. 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](https://ventilatepro.com/exam/cli/troubleshooting/#recovery-reference).