MCP Server

HVAKR runs a Model Context Protocol (MCP) server so AI assistants — Claude, 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 three 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, and copy the token. 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 Notion

Notion’s AI agent registers itself dynamically, so 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 (with dynamic client registration) can connect to the same URL. 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, dryside_graph, ventilation, equipment, checksums, airflows). Omit include for every section (large).

listProducts / getProduct

listProducts browses the accessible product catalog (your organization’s products plus public ones), paginated ({ count, hasMore, nextCursor, products }; page with cursor) with an optional search over name/manufacturer/model; getProduct returns a single product’s 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 (OWNER only). 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 and auto-takeoff return queued — poll getJob until the status settles. 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.

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
• Member (role ≥ 4) — can additionally run the calculator and create or update projects
• Owner — can additionally delete projects

The assistant cannot see projects you don’t already have access to. Write tools respect the same roles as the app, so it can only change projects you could change yourself.

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.