MCP server

The @addresspenny/mcp npm package is a Model Context Protocol server that exposes Addresspenny's validation engine as tools any MCP-compatible agent can call. It is a thin adapter over the REST API — anything you can do through MCP you can do through HTTP, with the same credit cost.

For setup, see MCP Setup. For a public overview, see the AI Integration page. Source lives on GitHub.

Configuration

The server reads three environment variables, normally supplied through your MCP client's config file:

• ADDRESSPENNY_API_KEY — required. An API token with the addresses:write scope (or no scopes, for full access).
• ADDRESSPENNY_ACCOUNT_ID — required. Your account prefix ID (e.g. acct_…).
• ADDRESSPENNY_API_URL — optional. Defaults to https://addresspenny.com/api/v1. Override for staging or self-hosted.

Tools

validate_address

Validate a single postal address. Returns standardized components, deliverability, and the full raw payload. Consumes 1 credit.

Input:

{
  "address": "1600 Amphitheatre Pkwy, Mountain View, CA"
}

Output:

{
  "status": "validated",
  "original_input": "1600 Amphitheatre Pkwy, Mountain View, CA",
  "valid": true,
  "address": {
    "line1": "1600 Amphitheatre Pkwy",
    "line2": null,
    "city": "Mountain View",
    "state": "CA",
    "postal_code": "94043-1351",
    "country": "US"
  },
  "formatted": "1600 Amphitheatre Pkwy, Mountain View, CA 94043-1351, USA",
  "error": null,
  "raw": { "...full REST API payload for agents that want validation metadata..." }
}

bulk_validate

Validate up to 100 addresses in a single call. Consumes 1 credit per address. Returns an array of results in the same shape as validate_address, with per-entry errors where validation failed.

Input:

{
  "addresses": [
    "1600 Amphitheatre Pkwy, Mountain View, CA",
    "350 Fifth Avenue, New York, NY",
    "1060 W Addison St, Chicago, IL"
  ]
}

parse_and_validate

Extract every complete postal address from unstructured text (emails, chat messages, transcripts, scraped pages) and validate each one. Ideal for agents that are handed freeform user input and need clean, verified addresses out the other end.

Input:

{
  "text": "Please ship to our NY office at 350 Fifth Ave, New York, NY and the Chicago branch at 1060 W Addison St, Chicago, IL."
}

Consumes 1 credit per extracted and validated address. If no complete addresses are found, the response is an empty array and no credits are consumed.

Errors

When a tool call fails, the MCP response is marked isError: true and the content contains a human-readable message. Common cases:

• 401 Unauthorized — API token missing, revoked, or lacks the required scope.
• 402 Payment Required — account is out of credits.
• 422 Unprocessable Content — input was empty or malformed.
• 429 Too Many Requests — per-token rate limit exceeded (20/min for parse_and_validate, 60/min for validate endpoints).
• 502 Bad Gateway — the AI extraction step failed upstream; retry after a moment.

Versioning and updates

The MCP server follows semver. Because most clients configure it via npx -y @addresspenny/mcp, new releases are picked up automatically on the next client restart. Pin a specific version (npx -y @addresspenny/mcp@0.1.1) if you need deterministic behavior.