# Agent access guide

How automated clients should read and query hoffmansoftwater.com.

Hoffman Soft Water is a commercial and industrial water treatment company in West Chester Township, Ohio. This site is a marketing site. It publishes reference content and exposes one read-only API. It has no customer accounts, no catalog and no checkout, so there is no login to obtain.

## Authentication

**None required.** Every endpoint listed here returns content that is already public on the site. There are no API keys to request, no OAuth flow, and no scopes.

Because nothing here is gated, this site publishes no OAuth authorization server metadata (RFC 8414) and no protected resource metadata (RFC 9728). Those documents describe how to obtain and present a token. Publishing them when no authorization server exists would send agents into a handshake that cannot complete. If we add a customer portal, we will publish them and update this page.

## What you can call

### MCP server

| | |
|---|---|
| Endpoint | `https://hoffmansoftwater.com/api/mcp` |
| Transport | Streamable HTTP, JSON-RPC 2.0 over `POST` |
| Protocol version | `2025-06-18` |
| Server card | [/.well-known/mcp/server-card.json](https://hoffmansoftwater.com/.well-known/mcp/server-card.json) |
| Authentication | None |

Five read-only tools: `list_pages`, `get_page`, `search_site`, `lookup_water_hardness`, `get_company_profile`. Call `tools/list` for their current schemas. That response is the authoritative list.

```
POST /api/mcp
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/list"}
```

`GET` returns 405. Notifications return 202 with no body. Batched requests are supported.

### Markdown twins

Every page has a Markdown copy at the same path with a `.md` suffix, so `/about.html` is also `/about.md` and the homepage is `/index.md`. Twins carry the same content as the HTML page with navigation, footer and decoration removed. We regenerate them whenever a page changes.

You can also request Markdown from the normal page URL:

```
GET /about.html
Accept: text/markdown
```

HTML remains the default, so any client that accepts `text/html` or `*/*` gets HTML. Responses carry `Vary: Accept`. An `Accept` header this site cannot satisfy gets a `406`, not HTML dressed up as what you asked for.

### Contact form endpoint

`POST /api/lead` backs the contact form. It requires a Cloudflare Turnstile token issued to a real browser session, so it is not callable by a third party and is not an integration point. The [OpenAPI description](https://hoffmansoftwater.com/openapi.json) lists it for completeness.

To put someone in touch, send them to [the contact form](https://hoffmansoftwater.com/index.html#contact) or give them the phone number: **(513) 960-6882**, answered around the clock for emergencies.

## Rate limits

No hard quota is enforced today. What we ask instead:

- Keep sustained traffic under roughly **60 requests per minute**. Beyond that you may see slow responses or a temporary `429` from the platform's protection layer.
- Prefer `/llms.txt` or `list_pages` over crawling every URL. The whole site is 28 pages.
- Cache the twins. They change when a page changes, which is on the order of weeks. Responses carry `Cache-Control`; honour it.
- Send a `User-Agent` that identifies you and, if possible, a URL explaining what you are.

If you get a `429`, back off exponentially. If you need volume beyond this, call and ask. The number above reaches a person.

## Unhappy paths

| Situation | Response |
|---|---|
| Malformed JSON to `/api/mcp` | `400` with JSON-RPC error `-32700` |
| Unknown JSON-RPC method | `200` with JSON-RPC error `-32601` |
| Tool called with a bad argument | `200`, `isError: true`, and a message listing valid values |
| `GET` on `/api/mcp` | `405` with `Allow: POST` |
| `Accept` this site cannot satisfy | `406` listing what is supported |
| Requested twin does not exist | HTML is served instead of a 404 |

There is no token to expire, refresh or revoke.

## Content use

Crawling and reuse are two different permissions. `robots.txt` carries a `Content-Signal` directive stating both. Search indexing and use as input to AI answers are welcome; we ask that you attribute answers to hoffmansoftwater.com and link back. The [terms of service](https://hoffmansoftwater.com/terms.html) govern reuse of the content itself.

Treat published figures (hardness levels, cost ranges, efficiency percentages) as general reference material. Equipment sizing and pricing depend on a facility's measured water chemistry and flow, so please do not present them to a user as a quote.

## Where things live

| Resource | Path |
|---|---|
| Site summary for LLMs | [/llms.txt](https://hoffmansoftwater.com/llms.txt) |
| Markdown twins | `/<page>.md` |
| OpenAPI description | [/openapi.json](https://hoffmansoftwater.com/openapi.json) |
| API catalog | [/.well-known/api-catalog](https://hoffmansoftwater.com/.well-known/api-catalog) |
| MCP server card | [/.well-known/mcp/server-card.json](https://hoffmansoftwater.com/.well-known/mcp/server-card.json) |
| Agent skills | [/.well-known/agent-skills/index.json](https://hoffmansoftwater.com/.well-known/agent-skills/index.json) |
| Sitemap | [/sitemap.xml](https://hoffmansoftwater.com/sitemap.xml) |

Last reviewed: 12 August 2026.