Address Validator

What Address Validator does

The Address Validator MCP server exposes an HTTP service for checking raw delivery addresses. Its main operation, POST /validate, produces a normalized address with line1, line2, city, state, zip, and country. The response can also include latitude and longitude from Nominatim, a deliverability score, a confidence value, a degraded flag, and a cache key.

The service belongs to the 🗺️ Location Services category. It is intended for applications that need a structured address result before shipping, fulfillment, or delivery workflows continue. The repository also provides GET /manifest, which describes the service and its schema for x402 and MCP discovery.

How it works

Each validation request is paid. Without acceptable payment evidence, POST /validate returns 402 Payment Required and advertises the configured price and protocol. The default price is 0.02 USDC. With valid payment, the service validates and geocodes the address, then returns the result.

Repeated identical requests can be served from the cache rather than calling the external provider again. Redis can hold these cached results, although the application can start without Redis. PostgreSQL is used for the payment journal and is also optional at startup.

Provider failures do not automatically produce an invalid-address conclusion. Instead, the API can return HTTP 200 with degraded: true, allowing callers to distinguish an incomplete provider-dependent result from a confirmed validation outcome. Circuit-breaker and latency tests cover this behavior.

Setup and configuration

The documented local setup uses Python 3.12, a virtual environment, the main and development requirements files, and Uvicorn serving app.main:app on port 8000. Docker Compose is also available through the repository’s container configuration.

Configuration is read from environment variables or a .env file through pydantic-settings. Important settings include the payment secret, Smarty credentials, Redis and PostgreSQL URLs, x402 pricing, Base RPC details, and the public service URLs. The default listener is 127.0.0.1:8000; the deployment documentation places Nginx in front of the application.

Tools and capabilities

The Address Validator MCP server provides these documented HTTP routes:

• POST /validate for paid address validation.
• GET /manifest for service and schema discovery.
• GET /health for PostgreSQL and Redis status.
• GET /metrics for operational counters, cache state, and circuit-breaker state.
• GET /metrics/revenue for aggregated revenue views.
• GET / for service identity and links.

The validation path combines normalization, provider-backed address checking, geocoding, deliverability scoring, caching, and x402 payment handling. The repository also documents private dashboard and prospecting routes, plus public pricing and signup routes.

Limitations and notes

The Address Validator MCP server does not provide application-level rate limiting. The documented deployment relies on an Nginx edge limit of 10 requests per second per IP, with a burst of 20 and HTTP 429 responses beyond that limit.

Production payment verification uses on-chain USDC confirmation on Base by default. A shared-secret HMAC proof alone is not accepted in normal operation; synthetic HMAC proofs are restricted to the explicitly enabled TEST_MODE recipe and are marked as test transactions. The default configuration requires at least one Base confirmation and settlement before service delivery.

The service depends on external address-validation and geocoding providers for complete results. When a provider cannot be reached, callers must inspect degraded rather than treating every HTTP 200 response as a fully verified address. PostgreSQL and Redis are optional for startup, but their absence affects payment journaling or caching and is reported by the health endpoint.