OwnerSpec for AI agents: MCP server, A2A agent and discovery files

OwnerSpec publishes its content for agents the same way it publishes it for people: the figure, the formula and the source, with the canonical URL and the date the facts were last checked. This page is the technical reference for connecting an assistant to it.

Two layers: what to cite and what to call

The public citation layer is the set of canonical OwnerSpec web pages, one per fact (https://ownerspec.com/<category>/<layer>/<slug>/). Each page carries a short answer, a fact sheet (answer, formula or compatibility basis, inputs, assumptions, method, primary source), a facts-verified date, a typed source list and its own canonical URL. That URL is the citation target.

The machine-readable layer is how a compatible agent retrieves the same content in a cheaper shape: the Markdown twin of every page, /llms.txt, /llms-full.txt, /index.json, the MCP server at /mcp and the A2A agent at /a2a. These are retrieval interfaces. When information is retrieved through any of them, the canonical public page should be used as the citation target whenever one exists; never cite the endpoint or the Markdown URL.

Every tool response and every Markdown twin therefore carries, for each page: the canonical URL, the page title, the facts-verified date, the source list, the fact sheet, and the tool or representation it came from. Nothing on this page implies that publishing these interfaces causes any assistant, search engine or answer engine to index or cite OwnerSpec; they make retrieval and correct citation possible, and no more.

Endpoint

The MCP (Model Context Protocol) server is https://ownerspec.com/mcp. It is a stateless Streamable HTTP server: JSON-RPC 2.0 over POST, one JSON response per request, no sessions, no SSE stream, no authentication. GET returns 405 by design.

Adding it to a client

The tools

Every tool is read-only and annotated as such (readOnlyHint: true, destructiveHint: false).

Every tool answer ends with the URL to cite and, where the page carries one, the date its facts were verified. get_quick_answer also returns the page’s fact sheet verbatim: answer, formula or compatibility basis, inputs, output, assumptions, method and the typed primary source. The two ported calculator tools use exactly the formulas and constants printed on the calculator pages, and run_calculator ports nothing: it runs the page’s own calculator. A number from the tool and a number from the page therefore always agree (scripts/verify-build.mjs fails the build if they drift, and if a maintenance interval or an EPA limit the tools quote disappears from its page).

The MCP App

In hosts that support MCP Apps (Claude and ChatGPT among them), eight of the tools also render an interactive view in the conversation: the live calculator with the user’s numbers filled in, the water report as a flagged table, the maintenance plan with due dates, and cards for guides, parts and picks. The view is one self-contained HTML resource (ui://ownerspec/view-v1.html, text/html;profile=mcp-app) that loads nothing from any other origin. Its links open ownerspec.com pages only, and it never shows a price or a product link. When the user changes a calculator field, the view tells the assistant the new result so the conversation can continue from it. Hosts without app support get the same answer as text.

The server also exposes resources (llms.txt, llms-full.txt, the sitemap, the search index, the OpenAPI description, auth.md) and one prompt, answer_from_ownerspec, that walks an assistant through search, quick answer and citation.

Example prompts

• “My well water smells like rotten eggs. Which treatment class handles that?” (diagnose, then cite the guide)
• “Which filters fit an iSpring RCC7AK?” (part match, with the cross-reference page to cite)
• “My lab report says arsenic 12 ppb, nitrate 4 mg/L, iron 0.6 mg/L and pH 6.2. What is over a limit?”
• “What expansion tank do I need for a 40 gallon heater at 120 F and 70 psi?”
• “My Kidde smoke alarm chirps twice a minute. What does that mean?”
• “I have a furnace, a fridge with a water filter and a tank water heater. What maintenance is due?”
• “Size a softener for 4 people at 18 gpg with 1 mg/L iron, regenerating weekly.”
• “Convert 14 dH to grains per gallon and tell me if that is hard water.”

What it does not do

It does not sell, install or service anything, and it never fetches live prices or stock. It returns no product links: picks come with the review page that compares them. It gives no medical advice: contaminant figures are EPA, WHO or state limits quoted from the page that cites them.

Limits

Read-only, public, no rate limit published. Be a good citizen: identify your client with a descriptive User-Agent and cache index.json rather than searching a hundred times a minute.

A2A agent

An A2A (Agent-to-Agent) endpoint at https://ownerspec.com/a2a accepts a plain-language question in a SendMessage (or message/send) call and returns a completed task whose artifact holds the best-matching pages, their quick answers and the URLs to cite. The agent card is /.well-known/agent-card.json.

Affiliate disclosure

OwnerSpec is funded by affiliate commission. The MCP server and the MCP App return no product links and serve no ads: they return OwnerSpec pages. The review and parts pages they point to carry Amazon Associates links, where a purchase may earn OwnerSpec a commission at no extra cost to the buyer, and each of those pages carries the disclosure. Editorial content is free to read, with no paywall and no account.

Discovery files

Every page is also served as Markdown: append index.md to its URL, or send Accept: text/markdown.

Source code

The server is a single Cloudflare Pages Function, published under the MIT licence at github.com/ownerspec-com/mcp-server.

Policies

Editorial policy, affiliate disclosure, terms of use (quoting with attribution and a link is permitted), privacy. Questions: [email protected].