Phone Intelligence MCP for AI Agents

Turn raw phone numbers into structured, agent-ready intelligence.

Phone Intelligence MCP gives Claude, Cursor, AI agents, and MCP-compatible workflows one tool to normalize a phone number, evaluate its validity, identify country and line metadata, and return an actionable ACCEPT, REVIEW, or REJECT decision.

Why use it?

Most phone-number tools stop at valid: true/false. This MCP tool is designed for automated workflows that need a clear next action and structured evidence.

Use it to:

• clean and normalize CRM or lead phone numbers
• validate user-submitted phone data before downstream actions
• route records based on country or line type
• reduce malformed or suspicious phone data in agent workflows
• request premium live intelligence when the upstream service supports it

MCP tool

check_phone_intelligence

Checks one phone number and returns structured Phone Intelligence output.

Input

{
  "phone": "+33612345678",
  "expected_country": "FR",
  "live": false
}

Field	Required	Description
phone	Yes	Phone number in international or local format. E.164 is recommended.
expected_country	No	Expected ISO country code, such as FR, US, or GB.
live	No	When true, request premium live intelligence if supported by the configured upstream service. Defaults to false.

Output

The tool returns the upstream Phone Intelligence response as structured MCP content so an AI agent can use fields such as normalized number, validity, country, line metadata, decision, reasons, and evidence directly in its workflow.

Standard vs. live intelligence

live=false performs metadata-based phone intelligence. It does not claim that a line is currently reachable, currently assigned to a carrier, or ported unless those signals are explicitly returned by a live upstream provider.

live=true is reserved for premium live intelligence and may include additional network-derived signals when supported by the configured Phone Intelligence backend.

Example agent requests

• “Check whether +33 6 12 34 56 78 is a usable French phone number before I add it to the CRM.”
• “Validate this phone number and tell me whether the workflow should accept, review, or reject it.”
• “Check this number with live intelligence before the agent attempts contact.”

MCP endpoint

After deployment in Actor Standby, connect an MCP-compatible client to:

https://<actor-standby-url>/mcp

A health endpoint is also available at /health.

Configuration

Required environment variable:

PHONE_INTELLIGENCE_URL=https://<existing-phone-intelligence-endpoint>

Optional:

PHONE_INTELLIGENCE_TOKEN=<upstream-bearer-token>

Secrets should be configured in the deployment environment and never committed to source control.

Local development

npm install
cp .env.example .env
# Set PHONE_INTELLIGENCE_URL
npm run start:dev

MCP endpoint: http://localhost:3000/mcp
Health endpoint: http://localhost:3000/health

Billing

Pay-Per-Event event definitions are prepared for standard and live checks, but charging is intentionally disabled in this pre-launch package. Pricing must be confirmed before enabling Actor.charge(...).

Privacy and data handling

The MCP layer is a thin request/response gateway. It does not intentionally persist phone numbers itself. Data handling by the upstream Phone Intelligence service and Apify runtime should be documented in the final Store listing before publication.