vies-smoother

SLA'd EU VAT number validation for AI agents. Wraps the European Commission's VIES service (authoritative but flaky -- rate limits, per-country outages, inconsistent errors) with:

• A 24-hour cache
• A per-country circuit breaker (stops hammering a member state that's currently down)
• An honest three-state answer, never a guess:
  • valid -- the number is registered and active
  • invalid -- the number does not exist or is inactive
  • unavailable_upstream -- VIES is down and there's no cache; you are not charged for this

Free tier: 100 lookups per key, no card required. $0.01/lookup after that ($5 / 500-credit minimum top-up).

This repo is the MCP client only (a thin wrapper over the hosted REST API at https://vantane.com) -- it doesn't reimplement the cache/circuit breaker logic, which lives server-side so metering is centralized regardless of how you connect.

Quickstart

Claim a free key:

curl -s -X POST https://vantane.com/keys/claim

Option A: hosted, no install

Point any MCP client directly at the hosted endpoint:

{
  "mcpServers": {
    "vies-smoother": {
      "url": "https://vantane.com/mcp",
      "headers": { "X-API-Key": "sk_live_..." }
    }
  }
}

Option B: run this locally (stdio)

pip install -r requirements.txt
export RAILS_API_KEY=sk_live_...
python server.py

MCP client config:

{
  "mcpServers": {
    "vies-smoother": {
      "command": "python",
      "args": ["/path/to/server.py"],
      "env": { "RAILS_API_KEY": "sk_live_..." }
    }
  }
}

Tools

• validate_vat(country_code, vat_number) -- single lookup, 1 credit
• validate_vat_batch(items) -- up to 50 per call, 1 credit each

REST API (if you'd rather not use MCP)

• POST /keys/claim -- claim a free key
• POST /vies/validate -- single lookup
• POST /vies/validate/batch -- batch, max 50
• GET /vies/status -- live VIES availability, cache hit rate, 7-day SLA (free, no key)
• POST /topup -- buy more credits (requires an existing key)

License

MIT