MCP Server

HVAKR runs a Model Context Protocol (MCP) server so AI assistants (Claude, Codex, Microsoft Copilot, Notion AI, and any other MCP-aware client) can read your projects and run calculations on your behalf. The assistant signs in with a HVAKR access token, so it only sees the projects you can already access and respects your role on each one.

Server URL

https://mcp.hvakr.com/mcp

The server speaks MCP over Streamable HTTP and authenticates with OAuth 2.0. Use the in-app connector flow described below for the canonical setup. Most clients only need the URL and will walk you through the rest.

What you can do with it

Ask the assistant about your work in plain language:

• “List my active projects.”
• “Open the Riverside Office tower and tell me which spaces have the highest cooling loads.”
• “Run loads on project 12345 and summarize the peak hours for each zone.”
• “Search the product catalog for a 5-ton rooftop unit.”
• “What’s the design supply airflow for AHU-1 in this project?”

The assistant uses the tools listed below to fetch real data. It doesn’t guess project values from training data.

Connecting Claude

The fastest way to set this up is through the in-app dialog: in HVAKR, open Settings → Integrations → Claude → Connect and follow the two steps. The dialog generates the access token you’ll need and copies the server URL for you.

If you’d rather do it by hand:

1. Add a custom connector in Claude. Go to Settings → Connectors → Add → Add custom connector. Name it HVAKR and paste https://mcp.hvakr.com/mcp into the URL field. Leave Advanced settings blank. Click Add.
2. Authorize with an access token. Claude opens a HVAKR sign-in window. In HVAKR, go to Settings → Developer, click Create Access Token, name the token, click Create Access Token in the dialog, then copy it from the Save Your Token dialog. Paste it into the HVAKR sign-in window. The token goes to HVAKR, not Claude.
3. Start using it. Once authorized, Claude lists hvakr as an available connector. Mention “HVAKR” in a chat to nudge it to use the tools, or invoke one of the built-in prompts directly.

You can revoke access at any time from Settings → Developer by deleting the token.

Connecting Codex

In HVAKR, open Settings → Integrations → Codex → Connect. The dialog has two steps:

1. Add the HVAKR server. Run this command in your terminal:

   codex mcp add hvakr --url https://mcp.hvakr.com/mcp

2. Authorize with your access token. Codex opens a HVAKR sign-in window in your browser. If it doesn’t, run codex mcp login hvakr. Click Create Access Token in the dialog, copy the token, and paste it into that window.

The dialog’s Codex Docs button opens OpenAI’s Codex MCP documentation.

Connecting Microsoft Copilot

Microsoft Copilot connects through a Copilot Studio agent. In HVAKR, open Settings → Integrations → Microsoft Copilot → Connect, then follow the steps in Copilot Studio:

1. Add the HVAKR MCP server. In Copilot Studio, open your agent’s Tools page and select Add a tool → New tool → Model Context Protocol. Enter HVAKR as the server name and a description, for example: HVAKR projects, load calculations, and weather stations. Paste https://mcp.hvakr.com/mcp into the Server URL field. Choose OAuth 2.0 → Dynamic discovery, then select Create.
2. Authorize with your access token. When you create the connection, Copilot Studio opens a HVAKR sign-in window. Click Create Access Token in the dialog, copy the token, and paste it into that window.

Connecting Notion

Notion’s AI agent skips dynamic client registration, so the server registers Notion the first time it asks you to sign in. The flow is the same as Claude: add a custom MCP connector in Notion’s integration settings, paste https://mcp.hvakr.com/mcp, and sign in with a HVAKR access token when prompted.

Connecting any other MCP client

Any client that speaks MCP over Streamable HTTP and supports OAuth 2.0 can connect to the same URL. The server supports dynamic client registration, and it registers a client that skips that step on its first sign-in. Authorize with a HVAKR access token at the OAuth login screen. The server uses your token as the bearer credential on every request.

Tools

The assistant decides when to call these based on what you ask.

whoami

Returns the authenticated caller: identity, organization memberships, plan, and per-minute rate-limit budget. The recommended first call: it confirms the connection works and reports what you can do.

listProjects

Lists projects you have access to, paginated. Returns { count, hasMore, nextCursor, projects }; the assistant pages with cursor when there are more. Each summary has id, name, number, address, status, and projectType. Optional search (name/number/address), status, and projectType filters narrow the list.

getProject

Fetches a single project by ID. expand controls payload size: omit/false for the base project, true to inline every subcollection, or a list like ["spaces","zones","exports"] for just those. Expanded exports come back in the public export shape.

getProjectCalculations

Runs the HVAKR calculator (the same one that powers the app) once, and returns the sections you ask for via include (loads, register_schedule, graph, ventilation, equipment, checksums, airflows). Omit include for every section (large).

searchProducts / getProduct

searchProducts searches the accessible product catalog (your organization’s products plus public ones) and returns a page of cards (id, name, manufacturer, model, type) as { count, hasMore, nextCursor, products }. Optional search is a case-insensitive substring over name/manufacturer/model. Optional type is an exact node type (e.g. AIR_CLEANER) and can be used alone to browse. Default limit is 20 (max 100); page with cursor. getProduct returns a single product’s full specs.

createProject, updateProject, deleteProject

Write tools. createProject builds a project from an expanded project object; updateProject deep-merges a partial patch (set a field or subcollection document to null to delete it); deleteProject soft-deletes a project. The tool’s own description tells the assistant to treat this as Owner-only, stricter guidance than the Admin-or-Owner role the REST API and SDK actually enforce for the same action. That’s guidance to the model, not a server-side restriction: an Admin whose assistant calls deleteProject anyway will still succeed. Failed calls return the API error envelope plus a recovery hint.

createJob / getJob

createJob runs a job by type: auto-group and check complete synchronously and return a result; export, auto-takeoff, and auto-route return queued. Poll getJob until the status is completed or failed. auto-route routes ducts with the project’s saved routing constraints. Export jobs require a definition (load-calculation, basis-of-design, ventilation-csv, or hourly-loads-csv) and, once complete, also appear under getProject with expand=exports. REST and SDK clients upload PDFs separately and receive a sheet-upload job that is also polled through getJob; MCP intentionally has no binary upload tool. Once it completes, use updateProject to repair any unplaced pages, then run the project-wide auto-takeoff job. auto-takeoff adds the detected spaces to the project. Set commit: false to write them as suggestions to review in the app instead. MCP cannot accept suggestions, and a later auto-takeoff deletes the pending suggestions on the levels it runs.

Resources

The server publishes two read-only resources clients can fetch to ground themselves before they start calling tools:

• hvakr://schema/project-subcollections: the JSON Schema for every project subcollection, including foreign-key relationships between spaces, zones, and systems
• hvakr://guide/usage: a short workflow guide the assistant reads on first connect

Prompts

Two built-in slash prompts are available in clients that support them (Claude and Notion both do):

• Project overview (project-overview): pass a project ID and the assistant returns a structured summary of the project, its building layout, systems and zones, envelope, and team
• Analyze loads (analyze-loads): runs loads on a project, correlates results with space names, and flags spaces or zones that look unusually high

Access levels and permissions

The MCP server uses the same role model as the rest of HVAKR. Your access token inherits your role on each project:

• Viewer (role ≥ 1): can list projects and call getProject and getJob
• Member (role ≥ 4): can additionally run the calculator and create or update projects
• Admin & Owner (role ≥ 8): can additionally delete projects; this is the enforced permission, matching the REST API and SDK

The assistant cannot see projects you don’t already have access to. Write tools respect the same roles as the app, with one caveat: the deleteProject tool is instructed to treat deletion as Owner-only, so a well-behaved assistant will push back on an Admin’s delete request, but nothing enforces that server-side, so don’t rely on it as a permission boundary.

Token security

The access token is the assistant’s only credential. Treat it the same way you’d treat any API key:

• Don’t share it or paste it into untrusted clients
• Rotate it periodically from Settings → Developer
• Delete the token if you suspect it’s been exposed; the assistant will be signed out immediately

Pricing

The MCP server is included on plans with API access. Calculator runs (getProjectCalculations) count against the same usage meter as the REST API.

Support

Have an MCP client that won’t connect, or a tool you wish the server exposed? Email support@hvakr.com with the client name and what you’re trying to do.