# Postal Data API — how to use (mcp.ai)

Connect your Postal Data API account and use 6 tools for developer tools straight from your AI agent. Connect with your own API key. Postal Data API validates and looks up postal codes, locations, coordinates, and regional metadata across more than 240 countries and territories.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_postal_data_api?ms=1787291160000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `postal_data_api_get_api_information`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/postal_data_api`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/postal_data_api/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/postal_data_api/get/api/information` — Return Postal Data API version, coverage, usage guidance, current balance, and configured rate-limit status when returned, for connectivity or service discovery. The provider does not document this en
- `POST https://api.mcp.ai/api/postal_data_api/get/postal/code/metadata` — Return all available country-specific metadata for a postal code, such as coordinates, timezone, county, elevation, and administrative levels. The metadata fields vary by country and availability. Eac
  - body: { postal_code: string, country_code?: string }
- `POST https://api.mcp.ai/api/postal_data_api/lookup/postal/code` — Look up the city, region, and coordinates for a postal code. Use this for a concise location result; use Get Postal Code Metadata for country-specific administrative details. Each successful call cons
  - body: { postal_code: string, country_code?: string }
- `POST https://api.mcp.ai/api/postal_data_api/search/postal/codes/by/city` — Return all postal codes matching a city and optional region, including fuzzy-match details. For US searches, provide a state name or state code. Each successful call consumes one Postal Data API query
  - body: { city: string, state?: string, state_code?: string, country_code?: string }
- `POST https://api.mcp.ai/api/postal_data_api/validate/postal/code` — Check whether one postal code exists without treating a nonexistent code as an execution error. Inspect valid in the response. Each successful call consumes one Postal Data API query.
  - body: { postal_code: string, country_code?: string }
- `POST https://api.mcp.ai/api/postal_data_api/validate/postal/codes/bulk` — Validate 1 to 1,000 postal codes synchronously, including mixed-country batches. Results preserve input order and report per-record failures. A batch of N records consumes N queries and is rejected at
  - body: { records: object[] }

## Example prompts
- "What can I do in Postal Data API?"
- "Show me a summary of my Postal Data API account"

## More
- Page: https://mcp.ai/postal_data_api
- Agent spec (llms.txt): https://mcp.ai/postal_data_api/llms.txt
- Postman collection: https://mcp.ai/postal_data_api/postman.json