online.numbers/numbers-online

Official4 tools

by numbers-online

Numbers Online — phone intelligence

Read-only phone intelligence for AI voice agents — line type, risk, DNC, signed receipts.

Phone number intelligence service providing line type, risk assessment, and DNC status for AI voice agents.

Captured live from the server via tools/list.

phone_lookup

Return a supplementary, low-confidence intelligence bundle for a phone number: validity, formatting, line type, range carrier, country, caller name (CNAM, where available), STIR/SHAKEN verstat (supply the call's verstat to fold it into the spam signal), a labeled spam signal, and a first-party do-not-contact (DNC) signal — a suppression preference registered by the number's own owner, never a copy of any government registry. Advisory only — the agent keeps every routing and dialing decision.

Parameters (3)

numberstringrequired
Phone number in E.164, e.g. +14155552671 (loose input is normalized).
verstatstring
Optional STIR/SHAKEN verstat for THIS call — TN-Validation-Passed / -Failed / No-TN-Validation, or a full Identity / P-Asserted-Identity header value. When supplied it folds into the risk signal (a failed validation raises it).
max_cache_age_secondsinteger
Operator TTL control; 0 forces a fresh dip.

line_type

Return only the deterministic fields for a number — validity, line type (mobile / fixed line / VoIP / …), range carrier, country, and formatting. No paid dip; a free, fast classification a voice agent can call before deciding to enrich.

Parameters (1)

numberstringrequired
Phone number in E.164, e.g. +14155552671 (loose input is normalized).

caller_risk

Return a labeled, low-confidence risk read for an inbound caller: a spam signal (0–100, higher = riskier), verstat passthrough, and a first-party do-not-contact (DNC) signal — without a name dip. A supplementary input to the agent's own policy, never a verdict on whether to accept or reject the call. Supply the call's STIR/SHAKEN verstat to fold it into the signal — a failed validation raises the risk.

Parameters (2)

numberstringrequired
Phone number in E.164, e.g. +14155552671 (loose input is normalized).
verstatstring
Optional STIR/SHAKEN verstat for THIS call — TN-Validation-Passed / -Failed / No-TN-Validation, or a full Identity / P-Asserted-Identity header value. When supplied it folds into the risk signal (a failed validation raises it).

dnc_check

Return a first-party do-not-contact signal (suppress / no_match / unknown) for a number, sourced ONLY from suppression preferences registered and verified by the number's own owner inside Numbers Online — never a copy of any government or licensed do-not-call registry. "suppress" = the owner asked not to be contacted on this channel; "no_match" = no suppression preference on record (absence of suppress is not consent); "unknown" = the number could not be evaluated. Comes with a signed receipt recording the status "as of T". Advisory input to the agent's own process — it does not assert that a call is lawful.

Parameters (1)

numberstringrequired
Phone number in E.164, e.g. +14155552671 (loose input is normalized).

README.md5 KBView on GitHub

Numbers Online — phone-intelligence MCP server

A hosted, read-only Model Context Protocol server that gives an AI voice agent phone intelligence in a single call: who is this inbound caller, and is this outbound number one to think twice about dialing — before it burns agent minutes.

Endpoint: POST https://numbers.online/api/v1/mcp (Streamable HTTP, JSON-RPC 2.0)
Transport: remote / hosted — nothing to install or run. Point your agent at the URL.
Auth: Authorization: Bearer <api_key> for tool calls; discovery is public.
Docs: https://numbers.online/docs/integrations · Site: https://numbers.online

Positioning. Every output is an advisory, low-confidence supplementary signal. The calling agent keeps every routing and dialing decision and remains responsible for compliance. Nothing here asserts that a call is lawful, unlawful, "safe", or "spam".

Tools

Four read-only tools (all annotated readOnlyHint, idempotentHint). Discover them live with tools/list (no auth required).

Tool	Returns	Billed
`phone_lookup`	Full bundle — validity, formatting, line type, range carrier, country, caller name (CNAM where available), STIR/SHAKEN verstat, a labeled spam signal, first-party DNC signal, signed receipt	bundled per-call
`caller_risk`	Spam signal + verstat + first-party DNC signal + receipt (no name dip)	bundled per-call
`line_type`	Deterministic only — validity, line type (mobile / fixed line / VoIP / …), carrier, country, formatting	free
`dnc_check`	First-party do-not-contact signal + signed receipt	free

About the DNC signal

The DNC signal is first-party, consent-first: it reflects a do-not-contact preference registered and verified by the number's own owner inside Numbers Online. It is not a copy, mirror, or replica of any government or licensed do-not-call registry. The values:

SUPPRESS — the owner registered a do-not-contact preference for this channel.
NO_MATCH — no suppression preference on record (absence of suppression is not consent).
UNKNOWN — the number couldn't be evaluated.

Treat it as a supplementary input to your own TCPA process, never a verdict that a call is lawful. (Reassigned-number status is inherently a carrier/FCC dataset and is intentionally not offered as a first-party signal — there's no reassigned_check tool.)

Connect

Any MCP client (Claude Desktop, Claude Code, IDEs)

Add a remote server pointing at the endpoint. Example mcp.json fragment:

json

{
  "mcpServers": {
    "numbers-online": {
      "type": "streamable-http",
      "url": "https://numbers.online/api/v1/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

A key needs the mcp use case. initialize, ping, and tools/list work without auth (capability discovery); tools/call is fail-closed and requires the key.

Vapi

Register Numbers Online as an MCP tool — the transport literal is shttp (see integrations/mcp/vapi-mcp-tool.json). A Vapi custom-function-tool alternative lives at integrations/vapi/numbers-online-tool.json.

Retell

Point your agent's call_inbound webhook at the drop-in config in integrations/retell/inbound-webhook.json. It always returns HTTP 200 within Retell's budget (fail-open) so a slow lookup never keeps the caller ringing.

Full walkthrough: docs/ai-voice-agents.md.

Quick smoke test

bash

# discover tools (no auth)
curl -s https://numbers.online/api/v1/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# call a tool (needs an mcp-scoped key)
curl -s https://numbers.online/api/v1/mcp \
  -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"phone_lookup","arguments":{"number":"+14155552671"}}}'

Runnable reference clients (zero-dependency) are in examples/ — Node and Python.

Signed receipts (verifiable "checked as of T" evidence)

Every billable answer can carry a receipt_id and an Ed25519 response_signature. Fetch the receipt later — no API key required, the id is the capability:

code

GET https://numbers.online/api/v1/receipts/{id}

No raw phone number is stored — only number_hash = sha256(E.164). Verify with the public key at GET https://numbers.online/api/v1/publickey. A receipt is verifiable evidence that a status was checked at a point in time — not proof that dialing was lawful. Treat a receipt id as sensitive (a phone number is a small keyspace, so the hash is bindable to a candidate number).

Privacy

Raw phone numbers are never logged or stored; they are hashed (sha256). The MCP path is read-only and stateless. Privacy policy: https://numbers.online/privacy

Pricing

The full bundle is metered as one bundled per-call dip (validation + line type + risk + first-party DNC in a single call). line_type and dnc_check are free. See https://numbers.online for current rates.

Developer: Evergrow · Product: Numbers Online · Contact: contact@numbers.online · License: MIT

Install

claude_desktop_config.json

{
  "mcpServers": {
    "numbers-online": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://numbers.online/api/v1/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.