MCP Server
The Ideal Postcodes API is an MCP server at https://api.ideal-postcodes.co.uk/mcp. An agent connected to it can verify and correct addresses, search for addresses it is unsure of, look up postcodes and UPRNs and validate emails and phone numbers. No integration code is needed.
Requirements
- An MCP client that speaks protocol revision
2026-07-28. The server supports that revision only. Clients that stop at2025-11-25or earlier cannot connect. See Supported clients - A backend API key. A key with no Allowed URLs. MCP requests come from a server, not a web page, so a key restricted to URLs is refused.
- A lookup balance. Tools bill exactly as the API endpoints they mirror.
Authentication
Send your API key as a Bearer token on every request:
Authorization: Bearer ak_...
- Header only. Never put the key in the URL. A key in a query string ends up in access logs, proxy logs and referrers.
- Licensees send their own key,
Authorization: Bearer sl_.... Usage is attributed to the licensee, as it is over HTTP. - No OAuth. The server publishes no OAuth metadata. A client that can only connect through OAuth discovery cannot connect.
Every other key check applies as it does over HTTP: IP restrictions, limits, licensee rules and balance.
Tools
| Tool | Mirrors | What it does |
|---|---|---|
cleanse_address | POST /v1/cleanse/addresses | The primary address tool. Verifies a full address and corrects it to its official form: one best match |
suggest_address | GET /v1/autocomplete/addresses | Speculative search for an address the model is unsure of: several candidates, best match first. Can be restricted to a postcode or dataset, ranked near a point, or given any other filter or bias the endpoint takes through filter |
resolve_address | GET /v1/autocomplete/addresses/{id}/gbr | The full address for a suggestion the model or user chose |
lookup_postcode | GET /v1/postcodes/{postcode} | The addresses at a postcode in the UK, Ireland, the Netherlands or Singapore, 100 per page. Suggests nearby postcodes when the postcode does not exist |
lookup_uprn | GET /v1/addresses?uprn= | The UK postal address for a UPRN |
validate_email | GET /v1/emails | Whether an email address can receive mail, with a suggestion when the domain looks misspelt |
validate_phone | GET /v1/phone_numbers | Whether a phone number is reachable, with its country, formats and network |
Start with cleanse_address. A model usually holds a full address and wants it verified. Cleanse returns the one best match, corrected to its official form.
Use suggest_address when the model is not sure what the address is: the text is partial, mistyped or likely corrupt. It searches speculatively and returns several candidates to compare. Filters and biases narrow them. It is quick enough to call repeatedly as the query is refined. The model then picks a candidate or asks the user, then calls resolve_address for the full address.
filter takes any other filter or bias of GET /v1/autocomplete/addresses by its API name, for example {"post_town": "london", "bias_thoroughfare": "high street"}. A filter excludes non-matches; a bias_ name only ranks matches first. Names the country does not support are ignored, and the typed arguments win over the same name in filter. Up to 10 entries, each value up to 128 characters.
The tool list is the same for every key.
Billing
A tool call costs the same as the API endpoint it mirrors, and runs that endpoint's own key checks.
suggest_addressis free, but needs a positive balance.resolve_addresscosts one lookup.- A postcode that does not exist costs nothing.
BR8 7REis a free test postcode: real data, answered in full, never billed.
Try it
Call a tool with curl:
curl -s https://api.ideal-postcodes.co.uk/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'Authorization: Bearer ak_...' \
-H 'MCP-Protocol-Version: 2026-07-28' \
-H 'Mcp-Method: tools/call' \
-H 'Mcp-Name: lookup_postcode' \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "lookup_postcode",
"arguments": { "postcode": "BR8 7RE" },
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}'
The server is stateless: there is no initialize handshake and no session. Each request carries its own protocol version and key. The Mcp-Method and Mcp-Name headers must match the body.
Supported clients
A client needs two things: MCP protocol 2026-07-28 and a static Authorization header. As of November 2026:
| Client | Connects? |
|---|---|
| Claude Code | Yes |
| Codex CLI | Yes, with an opt-in feature flag |
| TypeScript MCP SDK | Yes, with versionNegotiation set |
| Cursor | No. Its client stops at 2025-11-25 |
| VS Code (GitHub Copilot) | No. Its client stops at 2025-11-25 |
Clients not listed have not been tested.
Claude Code
claude mcp add --transport http ideal-postcodes https://api.ideal-postcodes.co.uk/mcp \
--header "Authorization: Bearer $IDEAL_POSTCODES_API_KEY"
Or commit it to the repo's .mcp.json, reading the key from the environment:
{
"mcpServers": {
"ideal-postcodes": {
"type": "http",
"url": "https://api.ideal-postcodes.co.uk/mcp",
"headers": {
"Authorization": "Bearer ${IDEAL_POSTCODES_API_KEY}"
}
}
}
}
Codex CLI
Codex speaks 2026-07-28 behind a feature flag that is off by default. In ~/.codex/config.toml:
[features]
mcp_2026_07_28 = true
[mcp_servers.ideal-postcodes]
url = "https://api.ideal-postcodes.co.uk/mcp"
bearer_token_env_var = "IDEAL_POSTCODES_API_KEY"
TypeScript MCP SDK
The @modelcontextprotocol/client v2 library uses the older handshake unless told otherwise. Pin the protocol version. mode: "auto" is not enough: it falls back to the older handshake, which the server refuses.
import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
const client = new Client(
{ name: "my-app", version: "1.0.0" },
{ versionNegotiation: { mode: { pin: "2026-07-28" } } }
);
const transport = new StreamableHTTPClientTransport(
new URL("https://api.ideal-postcodes.co.uk/mcp"),
// Sent as `Authorization: Bearer <key>` on every request
{ authProvider: { token: async () => process.env.IDEAL_POSTCODES_API_KEY! } }
);
await client.connect(transport);
const result = await client.callTool({
name: "lookup_postcode",
arguments: { postcode: "BR8 7RE" },
});
Errors
A missing or unknown key fails the HTTP request with 401 and code 4010. Everything else comes back as a tool result with isError set and the API's own error code, so the model can read it and tell the user.
| Failure | Response |
|---|---|
| Key missing or unknown | 401, JSON-RPC error 4010 |
| Unsupported protocol version | 400, JSON-RPC error -32022 |
Mcp-Method or Mcp-Name does not match the body | 400, JSON-RPC error -32020 |
| Body not valid JSON | 400, JSON-RPC error -32700 |
| Body too large or not UTF-8 | 413 or 415, JSON-RPC error -32600 |
Unknown tool, or malformed tools/call params | JSON-RPC error -32602 |
| Invalid tool arguments | Tool result, Input validation error: <field>: <issue>, so the model can correct the call |
| Key restricted to Allowed URLs | Tool result, 4011. Use a backend key |
| Sublicensed key sent without its licensee | Tool result, 4013 |
| No balance, limit reached, IP not allowed, inadequate licence | Tool result with the API's code, for example 4020 or 4291 |
| No match | An ordinary result: no addresses, or no confident match |
Negative codes are protocol failures. Positive codes are API refusals.
Limitations
- Protocol
2026-07-28only. Older clients are refused with-32022. - No OAuth. Authenticate with an API key in the
Authorizationheader. - No streaming. Every response is a single JSON body.
- Not in the OpenAPI spec.
/mcpspeaks JSON-RPC, so the API reference does not list it.