PhoneKit

PhoneKit — Phone Number Validation, Carrier & Line Type (MCP)

PhoneKit validates, normalises and enriches phone numbers for 240+ countries over a single HTTPS call: returns E.164, region/country, carrier, line type (mobile / landline / VoIP / toll-free / premium), time zones and validity. It's the right upstream for signup and checkout forms, CRMs, SMS/voice routing, KYC/fraud checks, marketing lists and diallers.

PhoneKit is published as an MCP server (streamable-HTTP transport). AI agents and tool-use runtimes call it directly via MCP tools — no wrapper or adapter. The same endpoint also serves the REST playground, so human developers and LLM tools share one URL.

Upstream and auth

• Upstream is a Cloud Run service (the same service that runs WebKit, DomainKit and GeoIP). The MCPize gateway proxies the public /phone/mcp endpoint to the live upstream.
• Auth is per-request: every call carries the X-Upstream-Key header with your plan's token. PhoneKit rejects unauthenticated calls. There is no separate user API key to rotate — the token is set when you subscribe.
• Rate limits, concurrency and the gateway's own 429/5xx handling are documented in the Plans section. All published plans use hard limits with no overage.

What the tools return

• validate: full validation and enrichment for a single number (E.164, country/region, carrier, line type, time zones, possible/valid flags). The response also includes the normalised international and national formats and a human-friendly country name.
• validate_all: bulk validation for up to 100 numbers in one call. Returns an array with one result per number plus a summary (totals of mobile/landline/VoIP/toll-free/premium/invalid). Ideal for deduping and scoring a list before upload.
• reverse: reverse lookup from an E.164 number — returns the same enrichment (carrier, line type, region) from the stored database. Useful when you already have an E.164 and just need carrier/line-type context.

Line type coverage PhoneKit classifies the line type the carrier or numbering plan exposes: MOBILE, FIXED_LINE (landline), FIXED_LINE_OR_MOBILE (numbering plan can't distinguish), VOIP, TOLL_FREE, PREMIUM_RATE, PERSONAL_NUMBER, SHARED_COST, VIRTUAL, PAGER, UAN, unknown and unclassified. That granularity is what fraud, routing and "can we SMS this?" decisions are built on.

Input

• A plain phone number string — with or without a +, with separators, in any format the customer actually types. PhoneKit normalises to E.164 and classifies.
• An optional country hint (2-letter ISO code). PhoneKit uses it only when the number is ambiguous; a number like +44... doesn't need it.

Errors

• Returns 422 when the input can't be parsed or the country hint is invalid. Returns 429 when a plan has hit its hard monthly limit (no overage). The MCPize gateway returns 429 / 5xx when the upstream or proxy is saturated — retry with backoff.

Typical uses

• Signup/checkout and account recovery: "real or VoIP?" before sending an SMS or calling the number.
• CRM and marketing dedupe: validate_all to score, classify and E.164-normalise a list in one call.
• SMS/voice routing: pick the right channel per line type.
• KYC, AML and fraud: flag VoIP, premium-rate and unclassified lines.
• Data quality: reverse to enrich an existing E.164 dataset with carrier and line type.

Plans Free 200/month; Starter $9.99 / 20,000; Pro $29.99 / 200,000; Business $79.99 / 2,000,000. Hard limits, no overage — you never get billed beyond your plan.