How to Build a Lead List (in Cursor)

TL;DR

• Cursor reaches LeadOcean through one mcp.json entry and a browser sign-in. You size the audience for free, spot-check five people, then export a CSV.
• It takes about 20 minutes. The count is free and the spot-check spends 5 of your 1,000 free records. Bulk CSV export is not on Free: the 100-row export needs Solo ($97 a month) or Agency ($497 a month).
• Counts, filter lookups and enum lookups cost nothing. Only people you receive count as records.

Prerequisites

• A LeadOcean account from app.leadocean.io. The free plan has no card and 1,000 records, one-off.
• Cursor installed. The Cursor MCP docs, September 2026, do not limit remote servers to a paid plan. On an Enterprise plan, an admin can limit servers to an MCP allowlist by URL, so ask for https://api.leadocean.io/mcp to be allowed if Cursor refuses the entry.
• For the export step: a LeadOcean paid plan (bulk CSV export is included on Solo and Agency, not on Free), and a key in your shell as $LEADOCEAN_API_KEY, plus curl and jq.

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

The MCP steps need no key. Setup details for the editor are on Connect LeadOcean to Cursor.

Step 1: Add the LeadOcean MCP server

Add one url entry to mcp.json. Use ~/.cursor/mcp.json for every project, or .cursor/mcp.json inside one project.

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

Do not add a headers block or a client ID. LeadOcean signs you in with OAuth 2.1 in the browser, and the server supports dynamic client registration, so Cursor registers itself.

Save the file, open the MCP list in Cursor and start the sign-in for leadocean. Your browser opens on LeadOcean. Approve, return to Cursor, and the tools appear. Button labels change between Cursor versions.

Step 2: Check the tools and your balance

The server exposes 13 leadocean_ tools. Seven never spend records: the two counts, filter list, enum list, account, get export and list exports. Cursor asks for approval before it runs an MCP tool, so read the arguments before you click.

Ask for your balance first. Type this into Cursor's chat.

Use leadocean_get_account. Tell me my plan and how many records I have left.
Do not search anything.

The REST route for the same check is free too.

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

Step 3: Size the audience for free

Write the audience as filters. This example is engineering directors at US software companies with 51 to 200 staff. Filters take exact strings, so check the industry value first.

Use leadocean_list_enum_values for industry with q "software". Then use
leadocean_count_leads with jobLevel ["Director"], jobFunction ["Engineering"],
industry ["Software Development"], employeeRange ["51-200"], country ["US"],
facets false. Report the total and say which email statuses it counted.
Do not call any tool that spends records.

The REST version is a people search with count=true as a query parameter 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 '{
    "jobLevel": ["Director"],
    "jobFunction": ["Engineering"],
    "industry": ["Software Development"],
    "employeeRange": ["51-200"],
    "country": ["US"],
    "emailStatus": ["verified", "catch_all_valid", "catch_all"],
    "limit": 1
  }' | jq '.meta'

If the number is too big or too small, change one filter and count again. Counting is free however often you do it.

Change one filter at a time so you know which one moved the total. Swap employeeRange first, then country, then add title keywords. Stop when the count is a list you could work in a month. The meta.total figure in a search is capped at 100,000, so a very wide audience shows a floor, not a true total.

Step 4: Spot-check five people

Look at real rows before you pay for 100 of them. Search returns thin records and no 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
is not an engineering leader so I can add it to excludeTitle.

Each person returned costs one record, so this step spends 5. The REST version is the same body with limit set to 5 and no count. Add excludeTitle (for example ["assistant","intern"]) if the sample shows noise. Search pages take limit 1 to 100 and continue with cursor.

Step 5: Export the list to CSV

Use an export for the bulk pull. Chat is a poor place for hundreds of rows, and an export writes one file. Bulk CSV export is included on Solo and Agency, not on Free. An export takes up to 50,000 rows a request and 500,000 a day. Each row costs one record whatever the columns, and a full export reserves twice the limit up front, then releases what it does not use.

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

Read perRow and remaining in the reply. They are the price of the job before it runs. The job then runs in the background. Poll every pollAfter seconds and 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

To stay in Cursor, ask for it in one prompt. The tools leadocean_export_leads and leadocean_get_export start the job and read its status.

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

Open leads.csv in the editor and read the email_status column before you load it anywhere. Verified and catch_all_valid addresses are the safest to send to. Bounced emails are not refunded, so drop anything you do not trust.

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 Step 3 run is real. On 21 October 2026 we ran leadocean_list_enum_values and leadocean_count_leads with the filters above. Both are free. The count returned this.

{
  "total": 928,
  "totalIsExact": true,
  "totalAll": 1888,
  "distinctCompanies": 650,
  "credits": 0,
  "defaults": "Counted only addresses worth sending to (emailStatus: verified or catch_all_valid or catch_all), which is this tool's default.",
  "sample": 1,
  "hasMore": true
}

The total describes the mailable audience, meaning verified, catch_all_valid or catch_all emails. It is not everyone matching the other filters: totalAll shows 1,888 with any email status or none. The 928 people work at 650 companies. Your number will differ as the data refreshes monthly.

We did not run the spending steps for this page. The export request 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 engineering directors at software companies",
    "status": "queued",
    "requested": 100,
    "perRow": "<records per row>",
    "remaining": "<records left after this reservation>",
    "pollAfter": "<seconds>",
    "file": null
  }
}

The finished download is a plain .csv, one row per person. Records are reserved when the export is admitted, and rows never written are released. The run should cost about 105 records: 5 for the spot-check and 100 for the export. On a paid plan those records count toward the fair-use pace, not a credit balance.

Troubleshooting

FAQ