# 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](#supported-clients).
* **A backend API key.** A key with no [Allowed URLs](/docs/guides/allowed-urls.md). 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:

```http
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                                                                                                                                                                                                         |
| ------------------ | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `verify_address`   | [`POST /v1/verify/addresses`](/docs/api/address-verify.md)                 | One 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_address`     | [`GET /v1/autocomplete/addresses`](/docs/api/find-address.md)              | Fast, 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_address` | [`GET /v1/autocomplete/addresses/{id}/usa`](/docs/api/retrieve-address.md) | The full address for a suggestion the model or user chose, in the US format. `remove_firm` drops the business name                                                                                                   |
| `validate_email`   | [`GET /v1/emails`](/docs/api/email-validation.md)                          | Whether an email address can receive mail, with a suggestion when the domain looks misspelled                                                                                                                        |
| `validate_phone`   | [`GET /v1/phone_numbers`](/docs/api/phone-number-validation.md)            | Whether 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](/docs/api/find-address.md) 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:

```bash
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:

| Client                                    | Connects?                            |
| ----------------------------------------- | ------------------------------------ |
| [Claude Code](#claude-code)               | Yes                                  |
| [Codex CLI](#codex-cli)                   | Yes, with an opt-in feature flag     |
| [TypeScript MCP SDK](#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

```bash
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:

```json
{
  "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`:

```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.

```typescript
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`](/docs/guides/error-codes.md#4010). Everything else comes back as a tool result with `isError` set and the API's own [error code](/docs/guides/error-codes.md), 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`                                                                        |
| Unknown suggestion `id` given to `retrieve_address`           | Tool result, `4048`                                                                        |
| No balance, limit reached, IP not allowed, inadequate license | Tool result with the API's code, for example `4020` or `4021`                              |
| No match                                                      | An 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](/docs/api.md) does not list it.
