Skip to main content

MCP Server

The AddressZen API is an MCP server at https://api.addresszen.com/mcp. An agent connected to it can verify and find addresses 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 at 2025-11-25 or 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​

ToolMirrorsWhat it does
verify_addressPOST /v1/verify/addressesOne address verified and corrected to its official form. US addresses are verified against USPS CASS, with ZIP+4 and delivery point details. Other countries with country
find_addressGET /v1/autocomplete/addressesFast, fuzzy search for the addresses a query could mean: several candidates, best match first. Searches the US unless given a country. Narrowed with filters and biases through filter, or ranked near a point
retrieve_addressGET /v1/autocomplete/addresses/{id}/usaThe full address for a suggestion the model or user chose, in the US format. remove_firm drops the business name
validate_emailGET /v1/emailsWhether an email address can receive mail, with a suggestion when the domain looks misspelled
validate_phoneGET /v1/phone_numbersWhether a phone number is reachable, with its country, formats, line type and network

Choosing an address tool​

verify_address first. A model usually holds the whole address already, from a form, a document or the conversation. Verify returns the one official address behind it, or says there is no confident match. It takes the whole address in query, or the first line in query plus zip_code, or city and state, when those are known separately.

find_address and retrieve_address when confidence is low. When the address is partial, garbled or fails to verify, find explores what it could be. It is quick and tolerates typos and missing parts, and returns several candidates. The model narrows them with filters and biases, calls again, then picks one or asks the user and retrieves it. Finds are free; each retrieve is billed.

filter takes any other filter or bias of GET /v1/autocomplete/addresses by its API name, for example {"state_code": "NM", "bias_city": "alamogordo"}. 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​

The same as the API endpoint it mirrors. Each tool runs the endpoint's own key checks and billing.

  • verify_address in the US costs one lookup for every address CASS answers, matched or not. A query that cannot be parsed costs nothing. Elsewhere only a match costs a lookup.
  • find_address is free, but needs a positive balance.
  • retrieve_address costs one lookup.

Try it​

Call a tool with curl:

curl -s https://api.addresszen.com/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: verify_address' \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "verify_address",
"arguments": { "query": "1010 cauthn ln, alamogordo nm 88310" },
"_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:

ClientConnects?
Claude CodeYes
Codex CLIYes, with an opt-in feature flag
TypeScript MCP SDKYes, with versionNegotiation set
CursorNo. 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 addresszen https://api.addresszen.com/mcp \
--header "Authorization: Bearer $ADDRESSZEN_API_KEY"

Or commit it to the repo's .mcp.json, reading the key from the environment:

{
"mcpServers": {
"addresszen": {
"type": "http",
"url": "https://api.addresszen.com/mcp",
"headers": {
"Authorization": "Bearer ${ADDRESSZEN_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.addresszen]
url = "https://api.addresszen.com/mcp"
bearer_token_env_var = "ADDRESSZEN_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.addresszen.com/mcp"),
// Sent as `Authorization: Bearer <key>` on every request
{ authProvider: { token: async () => process.env.ADDRESSZEN_API_KEY! } }
);

await client.connect(transport);
const result = await client.callTool({
name: "verify_address",
arguments: { query: "1010 cauthn ln, alamogordo nm 88310" },
});

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.

FailureResponse
Key missing or unknown401, JSON-RPC error 4010
Unsupported protocol version400, JSON-RPC error -32022
Mcp-Method or Mcp-Name does not match the body400, JSON-RPC error -32020
Body not valid JSON400, JSON-RPC error -32700
Body too large or not UTF-8413 or 415, JSON-RPC error -32600
Unknown tool, or malformed tools/call paramsJSON-RPC error -32602
Invalid tool argumentsTool result, Input validation error: <field>: <issue>, so the model can correct the call
Key restricted to Allowed URLsTool result, 4011. Use a backend key
Sublicensed key sent without its licenseeTool result, 4013
Unknown suggestion id given to retrieve_addressTool result, 4048
No balance, limit reached, IP not allowed, inadequate licenseTool result with the API's code, for example 4020 or 4021
No matchAn ordinary result: no suggestions, or no confident match from verify_address

Negative codes are protocol failures. Positive codes are API refusals.

Limitations​

  • Protocol 2026-07-28 only. Older clients are refused with -32022.
  • No OAuth. Authenticate with an API key in the Authorization header.
  • No streaming. Every response is a single JSON body.
  • Not in the OpenAPI spec. /mcp speaks JSON-RPC, so the API reference does not list it.