HeatPump AI MCP server
HeatPump AI exposes a Model Context Protocol (MCP) server so an outside agent — Meta Muse, Claude Code, Cursor, or any MCP-speaking client — can look up our manual-derived corpus of heat pump error codes and blink codes, and, with an API key, run a real paid diagnosis session. It is for developers who want to bring HeatPump AI's knowledge into their own agent or workflow.
Endpoint
https://europe-west1-heatpump-ai.cloudfunctions.net/mcp
Transport: streamable HTTP, POST only. The server is stateless — every request is handled independently, with no session kept open between calls.
Tools
Five free tools need no auth. Four paid tools need Authorization: Bearer hpk_....
| Tool | Auth | Inputs | Description |
|---|---|---|---|
list_families | none | — | Brands and model families HeatPump AI has data for. Call this first to get a brandSlug/familySlug. |
lookup_error_code | none | brandSlug, familySlug, code | Deterministic lookup of a displayed error/fault code. Says when a code needs a certified technician. |
list_blink_codes | none | brandSlug, familySlug | LED blink patterns the family reports faults with, when documented. |
search_manual | none | brandSlug, familySlug, query, locale | Keyword search over manual sections; returns section ids for read_manual_section. |
read_manual_section | none | brandSlug, familySlug, sectionId | A section's summary and fact list, in our own words. |
start_diagnosis | Bearer | brandSlug, familySlug, locale, model (optional) | Opens a paid diagnosis session for one family. Needs a positive credit balance; starting does not spend one. |
send_diagnosis_message | Bearer | sessionId, message | One paid, guardrail-checked AI turn. Charges credits only for a delivered answer. |
end_diagnosis | Bearer | sessionId | Closes the session. No charge. |
get_credit_balance | Bearer | — | The key holder's HeatPump AI credit balance. |
Getting an API key
- Sign in at
https://heatpump.nordmindai.com/account/. - Accept the two disclosure checkboxes (AI assistant notice and no-reliance notice).
- Create a key. It is shown once — copy it somewhere safe.
- Only one key is active per account. Creating a new key revokes the previous one.
- Revoke your key any time from the same page.
Send the key as Authorization: Bearer hpk_... on every paid-tool call.
A missing or revoked key does not produce an HTTP 401: the paid tool returns a normal MCP result with isError: true and a message saying a key is required. Check isError rather than the HTTP status.
Credits
Paid tools charge credits per delivered answer. Credits are bought in the HeatPump AI iOS app. Every new account starts with a starter credit grant (20 credits today). A diagnosis turn is charged by the answer's actual cost, so one turn can use several credits, and a long answer can use most of the starter grant. If your wallet is empty, a paid call returns an error telling the agent where to buy more.
What the answers contain
Answers are our own summaries and facts — never manual text verbatim. Every answer carries an AI disclosure and states its safety outcome. When a fault requires a certified technician, the answer gives the exact technician-required sentence and no repair steps. If you are building an agent on top of this server, relay those lines to your user verbatim rather than paraphrasing them.
Connecting
Claude Code:
claude mcp add --transport http heatpump <endpoint-url> --header "Authorization: Bearer hpk_..."Omit --header to use only the free tools.
Meta Muse: add a custom connector — paste the endpoint URL and your bearer key into Muse's connector form.
claude.ai custom connectors: not practical for a personal key today — the beta custom-connector feature only supports org-level static headers, so an individual member's own key cannot be wired in per-user through that surface.
ChatGPT: not supported yet — ChatGPT's connector model requires OAuth, which this server does not implement yet.
Limits
- No images over MCP — photo diagnosis is app-only for now.
- Coverage is limited to the heat pump families returned by
list_families; manual data is available in English, Norwegian, Swedish and Finnish. - Paid tools are rate limited per account (a burst of sessions or messages can be rejected); free tools are not per-account limited.
- Keys are personal — do not share yours.
Contact
info@nordmindai.com