agentic-house-search
An MCP server for UK neighbourhood research. Give it a postcode, get back what
the government's own open data says about that place — demographics, crime,
deprivation, prices, fibre, 5G, noise, transport, amenities, schools and
planning constraints — plus a searchable registry of the 45 datasets underneath.
It is the postcode report
with an agent-shaped front door. Both run the same provider modules, so a
threshold or a caveat is written once and shows up in both.
Connect
Nothing to install, no account, no API key. Paste this URL wherever your client
asks for a connector, custom integration or MCP server URL:
The connect page
has a copy button, one-click buttons for Cursor and VS Code, and the same
instructions per client.
Claude Code:
Anything that connects by editing JSON — Claude Desktop
(claude_desktop_config.json), a project .mcp.json, and most others:
GET /health says whether the endpoint is up, which is more useful than a
client that only reports "connection failed".
Or find it by name
This server is listed in the official MCP registry,
so a client with registry support can add it without being given a URL at all.
Search for agentic-house-search, or use the canonical name:
Anything resolving it programmatically can read the entry straight from the
registry API — it carries both install paths, the hosted endpoint and the npm
package, so a client can pick whichever it supports:
The listing's version tracks releases, so it is worth checking it against
/health if a client reports something unexpected — a stale listing means the
registry entry was not republished after a release, not that the server is
wrong.
Or run it yourself
Free, ungated and with no dependency on the hosted deployment. Requires Node 20+.
Tools
Examples
What the numbers mean
The point of this server is that every figure states what it actually describes.
Agents summarising it should carry that through:
- Geography varies by source. A census figure describes an LSOA — a
neighbourhood of roughly 1,500 people, not an address. A crime count describes
a 1 km square. Ofcom mobile coverage describes an entire local authority,
because that is the finest grain Ofcom publishes; two postcodes in the same
authority will always show identical mobile figures. Ofcom broadband is
per postcode.
- Coverage varies by UK nation, and is stated rather than hidden. Census
tables are England & Wales;
data.police.uk excludes Scotland; the Planning
Data platform, Defra noise and the DfE school register are England-only. Those categories come
back as out_of_coverage with the reason and a link to the devolved
equivalent — never as a zero or an empty result.
- Deprivation ranks are not comparable across nations. England, Wales,
Scotland and Northern Ireland each rank their own areas against their own
index over a different number of areas. The index and its size are always
returned;
postcode_compare refuses to let a cross-nation comparison pass
without a caveat.
- Police data depends on each force submitting. A very low count in a
built-up area is more likely a gap than a quiet street, and the report says so
when the count is implausibly low.
unavailable means not built yet, not "none" — currently the Defra noise
extract, which needs a polygon join that has not been run.
This is not a survey, a valuation or a conveyancing search.
Configuration
HTTP mode binds to 127.0.0.1 by default and is stateless: a fresh server per
request, so it scales horizontally with no session affinity.
Running it yourself is free and ungated, and stays that way. stdio has no
limits at all, and --http with no API_KEYS set is open. The rate limiting
exists so that a shared deployment is a good neighbour to the government APIs
underneath, not to nudge you toward a paid tier. There isn't one. See
COMMERCIAL.md for where that boundary sits and what would have
to be true before any of it were sold.
The hosted endpoint
https://agentic-house-search.vercel.app/mcp is this same package, built from
this repository, deployed as a serverless function
(api/mcp.mjs, vercel.json) on the same
host as the website, which scripts/stage-site.mjs assembles into public/ at
build time. It exists so that connecting takes a URL rather than a config file. It is unauthenticated
because there is nothing to authenticate: every source is public open data and
the server holds no per-user state.
Both HTTP hosts share src/http.ts, so the hosted endpoint and
your own --http cannot drift apart in how they speak the protocol.
Deploying it
This repository is the deployment. Vercel builds from GitHub: connect the
repo once, and every push to main redeploys the endpoint. There is no CLI step,
no separate copy of the source and nothing to remember to run — the same push
that updates the website updates the MCP server, and a revert reverts both.
Setup is once, in Vercel's Add New → Project → Import Git Repository. Two
things matter:
- Name the project
agentic-house-search. vercel.json carries every other
setting, but not the project name, and the project name is what the URL is
made of. Any other name and the documented URL is a lie — change it in
connect.html, server.json, both READMEs and index.html, or alias a
domain onto it.
- Leave the framework preset on "Other." The build command and output are
already in
vercel.json; a preset would override them.
The build runs npm ci && npm run build in mcp/, and AHS_JS_ROOT=js tells
the bundled function where the provider modules landed. .vercelignore keeps
the website's own files out of the upload, since Pages serves those and / here
redirects there.
npm run smoke:http drives the same entrypoint locally and runs in CI on every
push, so a deployment that would break should go red in Actions first.
server.json is the entry for the official MCP registry,
which is how a client can offer this server by name rather than by URL. Publish
it with the registry's own CLI (brew install mcp-publisher), from the
repository root:
Publish to npm first. The registry proves you own the package you point it
at by reading mcpName out of the published npm package and comparing it with
server.json#name — so it validates what npm already has, not what is in this
repo. A version listed in server.json that npm has never seen fails, and
because npm will not accept the same version twice, the fix is another bump.
npm run check:versions compares both fields locally and runs in CI.
Development
npm run build copies the repo's js/ provider modules into dist/js. That
copy is deliberate: the alternative is reimplementing eleven providers, their
thresholds and their coverage gates in TypeScript, which is exactly how the
website and the server would start disagreeing about the same postcode.
evaluation.xml holds ten verified questions for testing whether a model can
actually use these tools. Every answer comes from fixed geography, a dated
statistical release or the registry — never a live figure that moves monthly.
Licence and attribution
This server is CC0. The data is not: it is public sector information under the
Open Government Licence v3.0, plus OS and Royal Mail rights in the postcode
geography, and OpenStreetMap contributors (ODbL) for amenities. Every response
carries the attribution — please keep it attached.
