The MCP server

The MCP server lets an AI agent read and act on your organisation’s data the same way a script calling the REST API would — authenticated the same way, and never able to do more than the key it’s given allows.

What it is

MCP (Model Context Protocol) is a JSON-RPC 2.0 interface at /mcp, authenticated with the same Authorization: Bearer hsp_live_… API key as the REST API, checked against the same scopes. It exposes seven tools: list_work_orders, read_work_order, raise_work_order, assign_work_order, list_evidence, verify_record_hash, and get_contact_and_data_rights (the only tool that needs no scope at all). The two write tools — raise_work_order and assign_work_order — require the same work-orders:write scope the REST API’s own write endpoint enforces, so an agent can never do more than an API key already permits.

Before you start

Using the MCP server needs an API key (Platform plan, minted with organisation-admin access to Settings) with the scopes your agent’s tools need — see API keys and scopes.

How to do it

1. Mint an API key with the scopes your agent needs — work-orders:read/work-orders:write and surveys:read cover most agent tasks.
2. Point your MCP client at https://api.housingsurvey.pro/mcp, sending the key as a bearer token.
3. Call tools/list first to discover the available tools and their input schemas — this, along with initialize and ping, is never rate-limited.
4. Use verify_record_hash to have the agent independently confirm a specific finalized survey hasn’t been altered — it re-derives the hash server-side rather than trusting anything the client supplies.
5. Use get_contact_and_data_rights for a scope-free way to hand an agent HousingSurvey Pro’s own support contact and data-rights process, with no key required for that one call.

How it integrates

Every scoped tool call draws from the same per-organisation rate budget as the REST API — 240 requests per minute, shared, not additive — so an agent and a REST integration running at the same time share one allowance rather than getting one each. Every tool call that touches tenant data is written to your organisation’s audit log, exactly like a human or REST API action; mcp is recorded as the actor. A breach of the rate limit returns a proper JSON-RPC error object with HTTP 429 and the standard Retry-After/X-RateLimit-* headers, so a well-built client should never be surprised by it.

Common problems

• A tool call returns an “isError” result about a missing scope. The API key wasn’t minted with the scope that tool needs — mint a new key with the right scopes.
• Discovery calls (tools/list, initialize, ping) are being throttled unexpectedly. They shouldn’t be — only scoped, data-touching tool calls draw from the rate budget.
• verify_record_hash reports a mismatch. Treat this as a genuine integrity finding, not a client bug — the hash is recomputed server-side from the stored record, the same way the nightly chain-verification sweep does it.