# Address Validator [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/Kder974/address-validator  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/address-validator

## Description
Valide une adresse de livraison : normalisation, geocodage, score de livrabilite. x402.

## Claude Desktop Quick Installation
No confirmed install details yet, so no config is published. Follow the setup steps in the repository above.

## Documentation

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

_Full upstream README: https://allmcps.com/mcp/address-validator/readme_