# Phone Intelligence MCP for AI Agents (`tryva/phone-intelligence-mcp`) Actor

MCP gateway for structured phone intelligence: normalize numbers, evaluate validity, identify country and line metadata, and return ACCEPT, REVIEW, or REJECT. Standard mode avoids unsupported live-network claims; live mode uses the existing backend.

- **URL**: https://apify.com/tryva/phone-intelligence-mcp.md
- **Developed by:** [smile flow](https://apify.com/tryva) (community)
- **Categories:** Developer tools
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 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**

```json
{
  "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:

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

A health endpoint is also available at `/health`.

### Configuration

Required environment variable:

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

Optional:

```text
PHONE_INTELLIGENCE_TOKEN=<upstream-bearer-token>
```

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

### Local development

```bash
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.

# Actor input Schema

## `phone` (type: `string`):

Phone number in international or local format.

## `expected_country` (type: `string`):

Optional ISO alpha-2 or alpha-3 country code.

## `live` (type: `boolean`):

Request premium live intelligence when supported.

## Actor input object example

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

# Actor output Schema

## `data` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("tryva/phone-intelligence-mcp").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("tryva/phone-intelligence-mcp").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call tryva/phone-intelligence-mcp --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,tryva/phone-intelligence-mcp"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/kbMXgMwXVHkzMc9Cy/builds/WQhSW0hiAXid3o0UV/openapi.json