How to give an AI agent UK property data with MCP

To give Claude, Codex or Cursor UK property data, connect the Homedata MCP server using npx -y homedata-mcp and your Homedata API key. Your agent can then look up addresses and property records through tools instead of guessing from its training data. Prefer Python? Use pip install homedata-mcp. The server runs on your machine; the ChatGPT app needs a hosted MCP server and cannot connect to this local package today.

Why an agent needs a property data tool

A language model may explain EPC bands or recognise a street name, but that does not give it the property’s recorded EPC, a resolved address or recent sale history. MCP (Model Context Protocol) lets the agent request structured data from an external service during your conversation. Homedata’s server sends those requests to the property API using your key.

That gives you a record to inspect. It does not make old source records new: coverage and freshness depend on the dataset and location. Ask the agent to report dates, missing values and the address it actually matched.

1. Get a key and choose an install

Create a Homedata account and generate an API key in the developer dashboard. Fund your account before paid lookups; check current API pricing. Calls made by an agent are still API calls, so agree a limit before letting it loop over a portfolio.

For the Node edition, install Node.js 18 or newer and use this launch command in your client configuration:

npx -y homedata-mcp

This starts a stdio MCP server. It waits for protocol messages from the client; it is not an interactive property search prompt. You do not need a global npm install.

For the Python edition, use an activated virtual environment with Python 3.10 or newer, then install and launch:

pip install homedata-mcp
homedata-mcp

Choose one edition. If the client cannot find homedata-mcp, use the full path to that executable inside your Python environment.

2. Connect your client

For Claude Desktop, merge the following entry into claude_desktop_config.json. On macOS that file is in ~/Library/Application Support/Claude/; on Windows it is in %APPDATA%\Claude\. Cursor uses the same JSON structure in ~/.cursor/mcp.json. Replace the placeholder with your own key and preserve any other configured servers.

{
  "mcpServers": {
    "homedata": {
      "command": "npx",
      "args": ["-y", "homedata-mcp"],
      "env": { "HOMEDATA_API_KEY": "YOUR_API_KEY" }
    }
  }
}

With the Python edition, change command to the path to homedata-mcp and remove args. Restart the client, enable the server if prompted, and check that Homedata tools appear. Keep your API key out of shared screenshots and committed project configuration.

Codex uses TOML in ~/.codex/config.toml:

[mcp_servers.homedata]
command = "npx"
args = ["-y", "homedata-mcp"]

[mcp_servers.homedata.env]
HOMEDATA_API_KEY = "YOUR_API_KEY"

Restart Codex and check the server in its MCP status view. The Codex setup guide covers the client steps; the MCP reference covers the server. An agent that can edit its configuration can also carry out the setup when you instruct it to install the package and supply the key securely.

3. Match an address before using property tools

If you already have a UPRN, give it to your connected agent. Otherwise, resolve the submitted address and postcode through the REST matching endpoint first. Do not assume an installed MCP package exposes a matching tool; inspect its available tools.

curl --get "https://api.homedata.co.uk/address/match/" \
  --data-urlencode "address=63 Harvey Lane" \
  --data-urlencode "postcode=NR7 0AG" \
  -H "Authorization: Api-Key YOUR_API_KEY"

Both address and postcode are required. HTTP 200 returns one property: the address-level retrieve body plus address_resolution, for 5 tokens. Confirm the returned address and resolution before asking the agent to enrich the UPRN through property tools.

HTTP 422 with reason no_match or multiple_matches returns no candidates and is never charged. Correct the submitted address or add missing flat or building details before retrying. Use the browser widget for typeahead forms.

Read what a UPRN is for the identity model, or the address match tutorial to build this flow in your own application.

When the lookup fails

• No tools appear: check the configuration syntax and executable path, then restart the client. Running the server in a terminal alone does not connect it to the agent.
• Authentication fails: check that the server receives HOMEDATA_API_KEY with a valid key. Restart after changing it.
• The API refuses a paid request: check the account balance and the returned error before retrying. Repeating an unchanged request will not fund the account.
• The wrong address appears: check the submitted address, postcode and address_resolution. Handle no_match or multiple_matches before requesting further records.
• A field is absent: have the agent say “not returned” and report the dataset’s scope. Do not let it fill the gap from a plausible guess.

Frequently asked questions

Can ChatGPT use this MCP server?

The ChatGPT app connects only to hosted MCP servers. Homedata’s published MCP server runs locally on your machine, so the app cannot use this one today. Codex, OpenAI’s coding agent, can use the local server.

Do I need both the Node and Python packages?

No. Choose Node with npx -y homedata-mcp, or install the Python edition with pip install homedata-mcp. Both provide an MCP server and the homedata CLI.

Does MCP make every property answer current and complete?

No. MCP retrieves API records at query time, but each underlying dataset has its own coverage and update schedule. Check the selected address, record dates and missing fields; a missing sale or EPC is not evidence that none exists.

Do I need an API key and a balance?

Yes. Supply your Homedata API key through HOMEDATA_API_KEY and fund your account for paid lookups. MCP requests use the same API pricing as other calls; check the current pricing before running batches.