How to Build a Lead List (in Claude Code)

TL;DR

• Claude Code talks to LeadOcean through one MCP URL. You size the audience for free, then pull it as a CSV.
• It takes about 15 minutes. The example audience (313 mailable sales leaders) spends about 318 records of your 1,000 free ones.
• Sizing, filter lookups and enum lookups cost nothing. Only rows you receive count.

Prerequisites

• A LeadOcean account and API key from app.leadocean.io. The free plan has no card and 1,000 records, one-off.
• The key in your shell as $LEADOCEAN_API_KEY. The export step needs a key with the enrich scope, because the export reveals emails.
• Claude Code installed, and curl and jq for the REST steps.

export LEADOCEAN_API_KEY="paste-your-key-here"

Step 1: Connect the LeadOcean MCP server

Add the hosted server as an HTTP MCP server, then sign in. Claude Code's docs say to run /mcp inside a session to authenticate a remote server with OAuth. No key gets pasted into the chat.

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

/mcp

Pick leadocean in the panel and approve the sign-in. The server exposes 12 tools. Six never spend records: count, filter list, enum list, account, get export and list exports.

Step 2: Check your balance

Read the account before you spend anything. GET /v1/account is free and returns your plan, records used and remaining, and your export ceilings.

curl -s https://api.leadocean.io/v1/account \
  -H "x-api-key: $LEADOCEAN_API_KEY" | jq

In Claude Code you can ask the same thing in plain language.

Use the leadocean MCP server to read my account. Tell me how many records I have left. Do not search anything.

Step 3: Size the audience for free

Write the audience as filters, not as a story. This example is VP Sales and Head of Sales at US software companies with 51 to 200 staff. Ask for the count first.

Use leadocean_list_enum_values to resolve the exact industry value for "software".
Then use leadocean_count_leads with title ["VP Sales","Head of Sales"], country ["US"],
industry ["Software Development"], employeeRange ["51-200"]. Report the total and say
which email statuses it counted. Do not call any tool that spends records.

The same count over REST is a search with count set and limit at 1. It returns meta.total and no rows.

curl -s https://api.leadocean.io/v1/people/search?count=true \
  -H "x-api-key: $LEADOCEAN_API_KEY" -H "content-type: application/json" \
  -d '{
    "title": ["VP Sales", "Head of Sales"],
    "country": ["US"],
    "industry": ["Software Development"],
    "employeeRange": ["51-200"],
    "emailStatus": ["verified", "catch_all_valid", "catch_all"],
    "limit": 1
  }' | jq '.meta'

On 30 September 2026 the MCP count for this audience was 313 mailable people. Your number will differ as the data changes. If the count is too big or too small, change a filter and count again.

Step 4: Spot-check five rows

Look at real rows before you buy 313 of them. Five records is a cheap test of the title match. Search returns thin records: name, headline, current role, company, location and email flags, never addresses.

Use leadocean_search_leads with the same filters and limit 5. Show a table of name,
job title, company, company domain and email_status. Flag any title that does not
look like a sales leader so I can add it to excludeTitle.

The REST version is the same body with limit set to 5 and no count. Each person returned counts one record. Add excludeTitle (for example ["assistant","intern"]) if the sample shows noise.

Step 5: Export the full list to CSV

Use the export endpoint for the bulk pull, not a paging loop through the chat. Claude Code warns when MCP tool output passes 10,000 tokens and caps it at 25,000 by default, so hundreds of rows belong in a file.

An export takes the same filters, a limit and a column preset. The full preset reveals emails and phones. Each row costs one record, and an export takes up to 50,000 rows a request and 500,000 a day.

curl -s https://api.leadocean.io/v1/exports \
  -H "x-api-key: $LEADOCEAN_API_KEY" -H "content-type: application/json" \
  -d '{
    "name": "US sales leaders at software companies",
    "filters": {
      "title": ["VP Sales", "Head of Sales"],
      "country": ["US"],
      "industry": ["Software Development"],
      "employeeRange": ["51-200"],
      "emailStatus": ["verified", "catch_all_valid", "catch_all"]
    },
    "limit": 313,
    "preset": "full"
  }' | tee export.json | jq '.data | {id, status, requested, perRow, remaining, pollAfter}'

The job runs in the background. Poll every pollAfter seconds (10), then download when the status is done.

ID=$(jq -r '.data.id' export.json)
curl -s https://api.leadocean.io/v1/exports/$ID -H "x-api-key: $LEADOCEAN_API_KEY" | jq '.data.status'
curl -s https://api.leadocean.io/v1/exports/$ID/download -H "x-api-key: $LEADOCEAN_API_KEY" -o leads.csv

Prefer to stay in the chat? Ask for the same thing in one prompt. The MCP tools leadocean_export_leads and leadocean_get_export start the job and read its status.

Start a leadocean export with the filters above, limit 313, preset full. Poll it with
leadocean_get_export until it is done, then give me the download link.

The LeadOcean app has the same export on its Exports page. It has a filter builder, a column picker, the record price before you start and a Download button.

What you get

The download is a plain .csv, one row per person. The full preset has 45 columns: identity, profile, contact flags, up to three emails and two phones, the current role, education and skills. The request itself returns HTTP 202 and a job.

This is the response shape from the API reference, with placeholder values.

{
  "success": true,
  "data": {
    "id": "<export id>",
    "name": "US sales leaders at software companies",
    "status": "queued",
    "requested": 313,
    "perRow": 1,
    "remaining": "<records left after this reservation>",
    "pollAfter": 10,
    "file": null
  }
}

A search page has a different shape: data is a list of people, each with profile_data, contact_data, resume_data and meta. The page-level meta carries count, limit, credits, total and nextCursor.

Step 3 gave us a real number: 313 mailable people on 30 September 2026, counted with the free MCP tool. Records are reserved when the export is admitted. Rows never written are released.

Troubleshooting

FAQ