HousingSurvey Pro for AI agents
HousingSurvey Pro runs a Model Context Protocol (MCP) server alongside its REST API v1, so AI agents and answer engines can read work orders and evidence, verify a record's tamper-evident hash, and raise or assign work — all under the same organisation-scoped permissions a human integrator gets, and all written to your append-only audit log.
https://api.housingsurvey.pro/mcphttps://api.housingsurvey.pro/v1Authentication
Bearer authentication with an organisation API key:
Authorization: Bearer hsp_live_...
An org-admin mints the key in the management portal under Integrations → API keys, choosing least-privilege scopes. Keys are shown once, stored only as a hash, and revocable instantly. The full model — and why we publish an honest oauth-protected-resource without a delegated authorization server — is documented in auth.md.
Available tools
| Tool | Scope | What it does |
|---|---|---|
list_work_orders | work-orders:read | List this organisation's work orders. Optional: status, jobType, limit (max 200). |
read_work_order | work-orders:read | Read one work order by id, including statutory-clock stage timestamps. |
raise_work_order | work-orders:write | Create a work order (property by uprn/propertyId/address, description, dueBy, jobType). |
assign_work_order | work-orders:write | Assign an existing work order to a surveyor already in your organisation. |
list_evidence | surveys:read | List finalized survey records (evidence) for a work order or the whole organisation. |
verify_record_hash | surveys:read | Re-derive a finalized survey's hash server-side and confirm it matches the stored chain — proves the record is untampered. |
get_contact_and_data_rights | none | How to contact us and how an organisation exercises data rights. No scope required. |
Machine-readable discovery
- MCP Server Card (SEP-1649) — also mirrored at /.well-known/mcp.json
- Agent Skills index (agentskills.io v0.2.0)
- OAuth Protected Resource metadata (RFC 9728)
- API Catalog (RFC 9727 linkset)
- OpenAPI 3.0 spec · Swagger UI
- auth.md — agent authentication & access metadata
- payments.md — payments & agentic commerce for agents
- llms.txt · llms-full.txt
Payments & agentic commerce
HousingSurvey Pro is sold by subscription (per-surveyor GBP seats), not as a retail catalogue — there's no shopping cart and no agent-executable purchase endpoint. Checkout is Stripe-hosted and always completed by a human; billing has no REST or MCP route at all. We deliberately don't publish discovery documents for x402, MPP, UCP, ACP or AP2 today, and never will for x402 specifically (no cryptocurrency, stablecoin or walletrail, full stop) — the honest reasoning for each, protocol by protocol, is at /payments.md.
Also part of the ProSurvey Apps family
The sister app DampApp Pro exposes its own agent interface for the independent-surveyor workflow. HousingSurvey Pro is the organisation-scale platform for housing associations, councils and their contractors.
Frequently asked questions
How does an agent authenticate to the HousingSurvey Pro MCP server?
With an organisation API key as a bearer token (Authorization: Bearer hsp_live_…), minted by an org-admin in the management portal under Integrations → API keys and scoped to exactly what the integration needs. The MCP tools enforce the same scopes as REST API v1, and every call is written to the organisation's append-only audit log. Full detail: https://housingsurvey.pro/auth.md
What can the MCP server do?
Read work orders and their statutory-clock timestamps, list finalized evidence, verify a record's tamper-evident hash, and raise or assign work orders — all scoped. It is a read-and-safely-act server, not a bulk-export firehose.
Where are the machine-readable descriptors?
MCP server card at /.well-known/mcp/server-card.json (also mirrored at /.well-known/mcp.json), Agent Skills index at /.well-known/agent-skills/index.json, OAuth Protected Resource metadata at /.well-known/oauth-protected-resource, API Catalog at /.well-known/api-catalog, and the OpenAPI 3.0 spec at https://api.housingsurvey.pro/openapi.yaml.
Can an agent buy or upgrade a plan directly?
No. Neither REST API v1 nor the MCP server has a billing route or tool — access is read-and-safely-act against an already-provisioned organisation only. Buying, upgrading and seat changes are Stripe-hosted checkout actions a human completes in the management portal. Full detail, including why agentic-commerce discovery protocols like x402, MPP, UCP, ACP and AP2 aren't published on this domain, is at https://housingsurvey.pro/payments.md.