Find Phone Number with MCP: Claude and Cursor Setup

Q: Can the agent find a phone number by name?

No. It needs a LinkedIn URL, a work email, a number or a person_id. Search by title and company domain first, then pass the person_id back. How to find a VP of Sales phone number walks through it. To run it over a list, use the Find Phone Number skill. The free plan is 1,000 records, one-off, no card. Each phone lookup uses 1.

Ask Claude or Cursor for a person's phone numbers and the agent calls find_phone. One URL, OAuth sign-in, 1 record per lookup.

This page is about setup and prompts. For the REST endpoint and the full field list, see Find a Phone Number. Other clients are on the MCP hub.

Connect the server

The server is https://api.leadocean.io/mcp. It signs in with OAuth 2.1, so there is no key to paste. Create a free account first.

Claude Code. The command format is from the Claude Code MCP docs, September 2026:

bash

claude mcp add --transport http leadocean https://api.leadocean.io/mcp
claude mcp login leadocean

The second command opens the browser sign-in. Running /mcp inside a session does the same.

Cursor. Add a remote server to mcp.json, in the url form shown in the Cursor MCP docs, September 2026:

json

{
  "mcpServers": {
    "leadocean": {
      "url": "https://api.leadocean.io/mcp"
    }
  }
}

Cursor starts the OAuth sign-in the first time the server is used. Other clients follow the same pattern, see the LeadOcean MCP docs.

The tool

The tool is find_phone. The server lists it as leadocean_find_phone. It costs 1 record per call.

Input	Type	Meaning
`linkedin_url`	URL	LinkedIn profile URL. Preferred key.
`email`	email	Work email, when you have no LinkedIn URL.
`phone`	string	A number you already hold, to find the rest we have for that person.
`person_id`	string	The `meta.source_ids.person_id` from a search row. Digits only.

Send one. The person_id key matters because about one person in five has no LinkedIn URL. It does not discover people: the tool answers about someone you can already name.

Prompts that work

Prompt	What the agent calls	Records
"Find the phone numbers for linkedin.com/in/jane-doe and tell me which one is the mobile."	`find_phone` with `linkedin_url`	1
"How many VPs of Sales in the US have a phone on file? Do not pull anyone."	`count_leads` with `hasPhone`	0
"Find 5 US VPs of Sales with a phone on file, then get the numbers for each. Stop at 10 records."	`search_leads`, then `find_phone` with `person_id` per row	10

Put the record limit in the prompt. Search returns one record per row, so the third prompt costs 5 for the search and 5 for the lookups.

The agent picks the tool from your wording. A question about size goes to count_leads, which is free. A named person goes to find_phone.

What the agent gets back

The MCP result is has_phone, a list of numbers best first, and a meta block. The shape is from the LeadOcean MCP reference, September 2026. Values below are placeholders.

json

{
  "key": "...",
  "has_phone": true,
  "contact_phones": [
    { "phone": "+14155550133", "type": "mobile", "dnc": null, "carrier": null, "priority": 1 }
  ],
  "meta": { "source": "...", "key_hash": "...", "schema": "..." }
}

has_phone: false means we hold no number. It does not mean the lookup failed. type is the source's own label, so treat an unfamiliar value as unknown.

Do-not-call is not answered. dnc is not populated at source, and null never means safe to call. Run your own check before dialling.

The REST twin is GET /v2/people/phone. It returns phones and best instead, as shown on the contact endpoints docs.

Free checks first

count_leads, list_enum_values and get_account spend no records. Run them before any paid call.

We ran count_leads on 2026-10-01 with jobLevel: VP, jobFunction: Sales & Business Development, country: US and hasPhone: true. It returned total: 252990, totalIsExact: true, credits: 0. That counts people with a phone number on file at that level and function. It is a phone count, not a mailable-email count.

Sizing first tells the agent how much a list is worth before it spends a record.

Troubleshooting

Error	Cause	Fix
401	The OAuth sign-in is missing or expired.	Run `claude mcp login leadocean` or `/mcp` in Claude Code. In Cursor, sign in again from the MCP settings.
402	The free 1,000 records are spent. The free plan is one-off, it does not reset.	Move to Pro at $499 a month.
429	Faster than 100 requests per second per key.	Wait the `Retry-After` seconds and retry. Ask the agent to work in small batches.
Wrong enum	A filter value is not in the catalogue, for example a made-up industry.	Call `list_enum_values` with a search term and use the exact string it returns.

FAQ

Do I need an API key for MCP?

No. The MCP server uses OAuth sign-in. The REST API uses an x-api-key header. Both draw on the same records.

What does a call cost, and what does a miss cost?

A found number costs 1 record. A person we hold no record for is a 404 and costs nothing. A person we know but with no number comes back as has_phone: false, and the docs price that REST answer at 1 record. Filter with hasPhone to avoid paying for empty answers.

Can the agent find a phone number by name?

No. It needs a LinkedIn URL, a work email, a number or a person_id. Search by title and company domain first, then pass the person_id back. How to find a VP of Sales phone number walks through it. To run it over a list, use the Find Phone Number skill.

The free plan is 1,000 records, one-off, no card. Each phone lookup uses 1.

Find your first phone number from Claude, free

Free to start. No credit card. 1,000 records to spend whenever you like.

Get your free API key →