ACURIS GEO · MCP SERVER

Acuris Geo MCP server

Give any AI agent — Claude, Cursor, ChatGPT, Gemini CLI and every other MCP-capable client — direct, self-describing access to Acuris address validation and geocoding. The MCP server sits on top of our REST API: every tool call is billed, refunded and rate-limited exactly like the API call it wraps, under your own API key.

Connect Tools Authentication Billing Local (stdio)

1Connect

The hosted endpoint is https://api.acuris-geo.com/mcp (streamable HTTP). Add it to your client with your Acuris API key as a bearer token:

Claude Code

claude mcp add --transport http acuris-geo https://api.acuris-geo.com/mcp \
  --header "Authorization: Bearer YOUR_ACURIS_API_KEY"

Claude Desktop / any JSON-config client

{
  "mcpServers": {
    "acuris-geo": {
      "type": "http",
      "url": "https://api.acuris-geo.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_ACURIS_API_KEY" }
    }
  }
}

Cursor

// .cursor/mcp.json
{ "mcpServers": { "acuris-geo": {
    "url": "https://api.acuris-geo.com/mcp",
    "headers": { "Authorization": "Bearer YOUR_ACURIS_API_KEY" } } } }

No key yet? Connect without one and call the request_trial_key tool with your email — you get an instant free trial key (100 credits, 7 days, no card). Then reconnect with the key.

2Tools

Tool	What it does	Cost
validate_address	Validate & standardize one address (240+ countries; UK via Royal Mail PAF with UDPRN + UPRN). Honest verdicts: `verified` / `corrected` / partial with reasons. Street-accurate USA/Canada matches include the free census enrichment block.	1 credit
validate_addresses_batch	Up to 50 addresses per call, mixed countries; UK rows routed per-row to PAF. Results in input order.	1 credit / row
enrich_us_ca_address	Address → census tract, block group, county/state FIPS, CBSA/MSA, congressional district, school district (USA) / dissemination area, census division, CMA/CA, federal electoral district (Canada).	1 credit (enrichment free)
geocode_address	Forward geocoding with an explicit `accuracy_type` on every result.	1 credit
reverse_geocode	Coordinates → nearest addresses with distances.	1 credit
expand_uk_postcode	UK postcode → every Royal Mail delivery point (organisation, UDPRN, UPRN, rooftop coordinates).	1 credit / postcode
check_balance	Remaining credit balances for the connected key.	free
request_trial_key	Instant free trial key by email (idempotent for 24h).	free

Failed lookups (no-match, errors) are refunded automatically — you pay for results, not attempts.

3Authentication

Send your Acuris API key as Authorization: Bearer <key> (or X-Acuris-Key). Trial keys via request_trial_key; paid keys with any plan from the pricing page. We recommend a dedicated key for agent use so you can rotate it independently.

4Billing & limits

Every tool call bills exactly like the underlying API call — same credits, same refunds, no separate MCP pricing.
Trial keys: 100 credits / 7 days, and a lifetime cap of 40 UK (Royal Mail PAF) lookups.
Per-IP velocity limits apply to your connection (the server forwards your real address), so one customer can never rate-limit another.

5Local (stdio) mode

Prefer a local process? Run the server over stdio with your key in the environment:

ACURIS_API_KEY=YOUR_KEY python3 acuris_mcp.py --stdio

Same tools, same billing. The hosted endpoint is recommended — zero install and always current.