MCP Server – Phone Intelligence for AI Agents

From a first lookup to a bulk job

1. Use a sandbox key and the documented sandbox numbers to check your integration without paid provider requests.
2. For live work, call vri_account_info, then vri_quote with the numbers and products you intend to request.
3. For one number, use vri_number_lookup. For up to 100 numbers, use vri_bulk_lookup. For an asynchronous job of up to 10,000 numbers, use vri_submit_job with a customer API key.
4. Set a unique request_id and a max_cost you approve. After a timeout, reuse the identical ID and arguments. A new ID starts a new paid operation.
5. For an accepted job, poll vri_bulk_status, then read vri_job_results. Pass each next_cursor back as cursor until it is null. Reading results does not rerun the lookup.

Use returned product availability to distinguish missing data from a negative verdict. For mobile, landline or VoIP interpretation, read the carrier classification guide. Carrier and caller-name records do not authenticate the person placing a call.

Example agent instruction: “Quote LRN and messaging for my list first. Show me the estimate before submitting. Once approved, submit once with a stable request ID and that cost limit. Retrieve all result pages and preserve the raw carrier classifications.”

Overview

The Model Context Protocol (MCP) is the open standard AI assistants use to call external tools. VeriRoute Intel runs a hosted MCP server, so an agent can check a number's current carrier, line type, or spam reputation — or submit a bulk job — in the middle of its own workflow, with no SDK or integration code.

Transport: Streamable HTTP (JSON-RPC 2.0 over POST). Supports HTTP clients using bearer keys or VRI OAuth. GET streaming is not provided; tool responses are returned as JSON.

Connect

Claude Code (CLI)

claude mcp add --transport http vri https://verirouteintel.com/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Claude.ai / Claude Desktop (custom connector)

Add a custom connector with URL https://verirouteintel.com/api/mcp. For OAuth, choose automatic client registration, sign in to VRI, and approve the connection. Alternatively, clients with request-header settings can send Authorization: Bearer YOUR_API_KEY. Use a test key while integrating. OAuth uses your live account.

Remote Claude connectors run from Anthropic’s servers. Browser inspectors may instead send requests from your browser; both use the same MCP endpoint.

Cursor / other MCP clients (mcp.json)

{
  "mcpServers": {
    "vri": {
      "url": "https://verirouteintel.com/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Authentication

Use your existing VeriRoute Intel API key as the bearer token — the same key that works on the REST API. Get one from Dashboard → API Keys. Initialization and tool discovery are public and do not perform lookups. Tool execution requires a valid API key or OAuth access token. A supplied invalid or revoked credential is rejected even for discovery. Keep credentials in authorization headers, never in shared URLs or browser-side application code.

Tools

Sandbox

A test key (from Dashboard → Sandbox) works over MCP too: the lookup tools return deterministic sample data for the sandbox magic numbers — no charges, nothing real dipped. Perfect for wiring an agent up before funding.

Billing

Live keys pay the same per-lookup rates as the REST API, deducted from your prepaid balance. Every result reports what it cost (total_charged); unavailable products are not charged. Partial lookups charge only for the products returned; fully unavailable lookups have no charge. A call that would exceed your available balance is refused up front with the amount needed.

Read the result before making another call

A successful HTTP response means the MCP exchange completed. Always inspect result.isError and the tool’s structured result. Single-number lookups return the same payload in structuredContent and JSON text.

Avoid duplicate spend: request all needed products in one vri_number_lookup call. vri_sms_deliverability performs another LRN and spam lookup; calling both on the same number charges for both sets of delivered results. Reusing a JSON-RPC ID does not deduplicate billing.

For safe retries, provide a unique request_id in the tool arguments. Reuse that ID with exactly the same arguments after a timeout: VRI returns the saved receipt without another lookup or charge. Changed arguments are refused. A pending receipt must not be resubmitted under a new ID; check vri_operation_status. Without a request ID, each call is a new operation.

Add include_sms_assessment: true to vri_number_lookup to obtain the SMS assessment from the same lookup. Required LRN and spam products are added once, avoiding a second overlapping call.

The SMS tool’s ok_to_message_now is false when reputation or line-type evidence is missing. It does not verify consent, DNC status, number ownership, or actual delivery.

Plan spending and retrieve results

vri_account_info returns available wallet balance and this connection’s controls. vri_quote accepts phone_numbers, products, and optional include_sms_assessment; it normalizes and deduplicates numbers, estimates the price, and performs no lookup. Both tools are free.

Paid tools accept max_cost in USD. If the estimate exceeds it, work is refused before lookup. Configure daily spending limits, allowed products, and bulk access under API Keys → MCP controls. Existing connections start without a daily limit. Controls apply to MCP, not REST calls. Estimates for pending operations and unfinished jobs count toward the budget for their UTC start date; completed work uses actual charges. Already accepted work may finish after a policy change.

After a job completes, call vri_job_results with job_id and optional limit (1–100, default 25). Pass each returned next_cursor as cursor until it is null. Reading stored results is free. Cursors expire after 24 hours and are bound to the account and job.

vri_operation_status accepts the returned operation_id and provides the saved receipt. Receipts belong to their original connection. Authentication and account restrictions still apply to retries.

{"name":"vri_number_lookup","arguments":{"phone_number":"2025550123","products":["lrn","spam"],"include_sms_assessment":true,"request_id":"your-unique-request-001","max_cost":0.02}}

Agent-readable reference

Use resources/list and resources/read for vri://reference/fields, vri://reference/coverage, vri://reference/billing, and vri://reference/examples. These contain public documentation, never customer records.

Limits and troubleshooting

MCP tool calls are limited per customer account across its keys: 6,000 calls/minute for single-number/status tools and 300 calls/minute for bulk lookup/job submission. These are request ceilings, not throughput guarantees. Synchronous bulk calls accept 100 numbers; asynchronous submissions accept 10,000.

vri_bulk_lookup returns results immediately. vri_submit_job returns a job ID: poll vri_bulk_status, then fetch the returned results_url with your REST API key when completed. The job ID belongs to the submitting account.

For client setup guidance, see Claude Code’s MCP documentation and Claude’s custom-connector instructions.

Raw JSON-RPC

Start with a test key from Dashboard → Sandbox. This example makes one tool call; a test key returns sample data without a charge. Use a live key only when you want a paid lookup.

curl -s https://verirouteintel.com/api/mcp \
  -H "Authorization: Bearer YOUR_TEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
      "name": "vri_number_lookup",
      "arguments": { "phone_number": "13364086644", "products": ["lrn", "spam"] }
    }
  }'

Find us in the MCP ecosystem

This server is published as com.verirouteintel/lookup in the Official MCP Registry, and listed on Smithery and MCP.so. The reference repo lives at GitHub.