APIs and MCP servers

Every calculator and every page here answers as JSON and over the Model Context Protocol. Neither needs a key or a sign-up. Requests are not stored, and the access log keeps only the request line. CORS is open to any origin.

An assistant answering questions about heat pumps or solar panels in UK homes can work from the published standards.

Endpoints

GET /api Discovery

Lists the calculator ids, the document endpoints and the two MCP URLs.

curl https://ampworth.com/api

GET /api/calculators List the calculators

Returns every calculator, the MCS standard it follows, a worked example request and the URL that runs it.

curl https://ampworth.com/api/calculators

GET /api/calculators/{id} Describe one calculator

Returns the fields it takes as a JSON schema, an example request, and the reference data those fields draw on, such as the solar zones and the design locations.

curl https://ampworth.com/api/calculators/solar-pv-output

POST /api/calculators/{id} Run a calculator

Send the request as JSON. Unknown fields are rejected, not ignored, so a typo is an error instead of a wrong answer.

curl -X POST https://ampworth.com/api/calculators/solar-pv-output \
  -H 'Content-Type: application/json' \
  -d '{"postcode":"BS1 5TR","capacityKwp":4.4,"orientation":30,"inclination":35}'

GET /api/documents List the documents

Lists every guide, article and question set. Filter with ?kind= or ?category=, and add ?full=true to include the full text.

curl 'https://ampworth.com/api/documents?kind=guide'

GET /api/documents/search Search

Ranks results across titles, summaries and text. Where a query matches one question inside a set, that question and its answer come back with it.

curl 'https://ampworth.com/api/documents/search?q=flow+temperature'

GET /api/documents/{kind}/{slug} Read one document

Returns the full text as plain prose, not markup, with the MCS documents it draws on and any calculators that do its arithmetic.

curl https://ampworth.com/api/documents/guides/sizing-a-heat-pump

POST /mcp/calculators MCP: calculators

A stateless server over streamable HTTP. It exposes every calculator as a tool, plus list_calculators, and the schemas come from the same structs the JSON API decodes.

{
  "mcpServers": {
    "ampworth-calculators": {
      "type": "http",
      "url": "https://ampworth.com/mcp/calculators"
    }
  }
}

POST /mcp/documents MCP: documents

A stateless server over streamable HTTP. It has three tools: search_documents, get_document and list_documents.

{
  "mcpServers": {
    "ampworth-documents": {
      "type": "http",
      "url": "https://ampworth.com/mcp/documents"
    }
  }
}

MCP tools

Both servers speak streamable HTTP and run stateless, so there is no session to hold. Input and output schemas are inferred from the same Go structs the JSON API decodes, which means the contract an assistant reads is generated from the code that answers it.

Tool	Server	Standard	Tier	What it does
`solar_pv_system_size`	calculators	MIS 3002	whole system	Works out the array a home needs — capacity, panels, battery and what it saves — from a postcode, a roof direction and a year of electricity use.
`heat_pump_size`	calculators	MIS 3005-D	whole system	Estimates a house's heat loss and the heat pump that covers it, from a year of gas or oil bills, and says whether a quoted size looks plausible.
`solar_pv_output`	calculators	MIS 3002	one method	Estimates a year of generation from a solar array using the MCS standard estimation method.
`solar_pv_shading`	calculators	MGD 005	one method	Turns a sunpath assessment into the shade factor an output estimate is multiplied by.
`solar_pv_self_consumption`	calculators	MGD 003	one method	Estimates how much of a solar system's output a household uses and how much it exports, with and without a battery.
`heat_pump_noise`	calculators	MCS 020	one method	Works out the sound pressure level at a neighbour's window and whether it clears the permitted development limit.
`room_heat_loss`	calculators	MIS 3005-D	one method	Works out one room's design heat loss, the figure a heat pump and its radiators are sized from.
`radiator_flow_temperature`	calculators	MGD 007	one method	Works out what flow temperature a radiator needs for its room, and the Heat Emitter Guide star rating that follows.
`hot_water_cylinder`	calculators	MIS 3005-D	one method	Works out a household's daily hot water demand and the cylinder a heat pump needs to meet it.
`heat_pump_running_cost`	calculators	MCS 007	one method	Compares a year of heating on the current fuel with the same heat from a heat pump.
`list_calculators`	calculators	—	—	Lists the calculators and every fixed set a caller may need to choose a value from.
`search_documents`	documents	—	—	Ranked search. A query matching one question inside a set returns that question and its answer.
`get_document`	documents	—	—	One document in full, as plain prose, with the MCS documents it draws on.
`list_documents`	documents	—	—	Everything covered, filterable by kind or category.

Things worth knowing

Unknown fields are rejected: A misspelled field name returns a 400. If it were ignored instead, the calculation would run without that input and hand back an answer that looked fine.
Validation errors arrive together: A 422 lists every bad field, each with a message naming what is wrong, so a caller can fix them in one round trip.
Every answer carries its assumptions: Results include the intermediate figures, the method, the MCS document it came from and any notes about how far the answer can be trusted. There is no need to fetch a second thing to interpret the first.
Rate limits: 120 requests a minute per address, on each surface. Nothing here reads or stores data, so the only thing being protected is CPU. A 429 carries a Retry-After.
The MCP servers are stateless: Each request carries its own short-lived session, so there is no session id to hold and nothing to expire. GET and DELETE return 405. POST requests must send Accept: application/json, text/event-stream.
The United Kingdom only: Design temperatures, irradiance zones, permitted development limits and network rules are all British. Applying any of it elsewhere will give an answer that looks reasonable and is wrong.