Connect an agent without handing it a mystery API.

Canonical MCP connection

Connect a Streamable HTTP client to the exact canonical endpoint below. The server is stateless per request and advertises current and legacy protocol compatibility from the endpoint itself.

Current implementation: water-heater-lookup version 0.21.0. Supported protocol versions: 2026-07-28, 2025-11-25.

Current deployed action mode

Agents should read both the machine-readable operating status and capability report immediately before a write. Do not send a write when operations are unavailable or that action is disabled. These short-lived low-cardinality reports never expose secret values or private records and do not claim provider coverage, delivery, legal approval, operator response, or production launch readiness.

One read for the common service journey

Start with plan_water_heater_service or POST /api/v1/service-plans when an assistant has a brand plus model or serial. Add an exact ZIP only when the person wants current provider discovery. The response keeps the full equipment evidence, directory state, deterministic next step, and pre-write checklist together. It rejects name, email, phone, and every other unexpected field; it never creates a handoff, contacts a provider, or submits a quote request.

One contract for the provider offer

Before an assistant quotes a provider plan, compares fit, or invites a business to apply, it should read the provider-program directory or waterheaterlookup://provider-program. Both return the same input-free, write-free contract for founding-market price hypotheses, ZIP limits, benefits, application and qualification stages, exact capability vocabulary, plan-neutral ranking and routing, billing boundaries, unfinished legal terms, and non-guarantees. Reading it does not apply, contact anyone, enable checkout, or prove billing is live. A provider application remains a separately authorized write, takes no payment, and enters manual review.

Bounded provider vocabulary

Use the capability enums in MCP or OpenAPI instead of guessing free text. diagnosis and repair are one service family; gas maps only to natural-gas. For a service plan, heat-pump equipment selects the heat-pump provider capability, while equipment fuel other or unknown does not become a provider constraint. The result returns its canonical query and constraintPolicy. No ZIP, brand, replacement, maintenance, recall, installation, emergency, propane, or other capability is widened.

Coverage state for empty results

Read the returned coverage.status instead of inventing a geographic conclusion. current-matches means at least one currently eligible record matched the exact ZIP and supplied constraints. With no match, network-building means the ZIP belongs to an onboarding, invite-only, or live sourcing market; outside-active-market means it does not. not-run means no exact ZIP was supplied. The response exposes no market name or ID, internal market status, provider target, readiness threshold, demand count, or private sourcing record. An empty result in either geography state does not prove that no qualified local professional exists. For an exact-ZIP search, providerApplicationUrl carries only the already-supplied ZIP in a coverage_zip fragment. The application removes it from the address bar, adds it to an editable browser draft, and makes no application, provider-attribution, or additional market-demand record merely by opening. Give the URL only to a provider who says the business serves that ZIP. It is not outreach authority, qualification, approval, listing, demand, service assurance, or a coverage promise.

Tools and consequences

Every write is retry-safe only when the client supplies its required idempotency key. Reuse one key solely after an uncertain result with exactly unchanged input; a completed retry returns the original receipt, while changed input under the same key is rejected. REST uses Idempotency-Key; MCP uses idempotencyKey. A provider application uses contactPhone for private review and a separately authorized publicPhone for customer contact; the private value is never published by fallback. Its service and fuel/technology values are bounded by OpenAPI: repair is stored as diagnosis, gas as natural-gas, and unsupported values reject the write. A provider-application receipt is deliberately neutral: it never reveals whether its email or license matches another private record.

Bounded resources

Agents can read methodology, the canonical supported-identifier directory, the canonical provider-program directory, point-in-time official-source status, service operating status, current deployed-action capabilities, and a provider record returned by exact-ZIP search. REST and MCP return identical input-free, write-free identifier and provider-program directories. The former publishes exact supported aliases, formats, examples, ambiguity, sources, and refusal boundaries; every unlisted serial family remains unsupported. The latter publishes the commercial offer and its application, qualification, ranking, billing, legal, guarantee, and privacy boundaries. Each provider includes an explicit REST recordUrl, an opaque public-only reference.version, and mustRevalidate: true; MCP results also include a resourceUri. A REST client may retain the response only in a private cache, send the prior ETag with If-None-Match, and accept 304 Not Modified only after the server rechecks current eligibility. A provider that is no longer current returns 404, even when the client has an older validator. MCP provider resources remain zero-TTL and must be reread directly. The opaque version is a comparison hint, never permission to rely on a retained copy. The returned phone is the provider-confirmed public customer-facing number; no private application or operator-review phone is substituted. Source status is cached for five minutes, operating status for one minute, and action capabilities for 30 seconds. None replaces the source states returned by an actual lookup or proves provider coverage or delivery. Provider IDs are neither listed nor autocompleted. A provider resource must be reread before presentation, contact, or routing because it disappears when qualification, access, capacity, or freshness is no longer current.

Evidence and safety boundaries

A lookup result is sourced screening—not inspection, diagnosis, warranty confirmation, or a safety guarantee. Exact model status requires a complete brand/model match to a current U.S.-market ENERGY STAR row without model wildcards; no match, conflicting rows, and catalog unavailability remain distinct. An empty recall search is never an all-clear. Agents should cite returned source URLs, preserve confidence language, and compare recall candidates with the complete official notice and equipment label.

Private service handoff first

When a person should supply their own contact details, prefer the private handoff tool. Before that person submits, Water Heater Lookup stores only an opaque handoff identifier, a one-way token hash, a private HMAC retry fingerprint, timestamps, and the interface source; service context remains in the private URL fragment. Direct quote submission is a distinct write action requiring explicit confirmation. After every current eligibility gate, its initial provider selection uses a retry-stable request-specific order that ignores plan, payment, business name, and alphabetical directory position; it is not a quality ranking, equal-share promise, or lead-volume guarantee.

Registry distribution

The publisher manifest uses the domain-owned name com.waterheaterlookup/water-heater-lookup. Manifest validation, domain authentication, and Registry publication are separate states: a valid manifest or reachable endpoint does not prove the server is published, approved, endorsed, or durable in a third-party registry.