How to Build a Lead List (in VS Code)

TL;DR

• VS Code chat reaches LeadOcean through one mcp.json entry and a browser sign-in. You size the audience for free, then pull it as a CSV.
• It takes about 15 minutes. The example audience (191 mailable engineering leaders) spends about 196 records. Bulk CSV export needs Solo ($97 a month) or above; on Free you page the rows with search.
• Counts, filter lookups and enum lookups cost nothing. Only rows you receive count.

Prerequisites

• A LeadOcean account from app.leadocean.io. The free plan has no card and 1,000 records, one-off.
• VS Code with chat set up. The VS Code MCP docs, October 2026, show how servers are added and managed.
• For the REST export step: a key in your shell as $LEADOCEAN_API_KEY, plus curl and jq. The export reveals emails, so the key needs the enrich scope.

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

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

Step 1: Add the LeadOcean MCP server

Create .vscode/mcp.json in your project with one http server. VS Code's config key is servers.

{
  "servers": {
    "leadocean": {
      "type": "http",
      "url": "https://api.leadocean.io/mcp"
    }
  }
}

Do not add a headers entry. LeadOcean signs you in with OAuth 2.1 in the browser, so there is nothing to paste.

Run MCP: List Servers from the Command Palette, pick leadocean and choose Start Server. Approve the sign-in in the browser, then return to VS Code.

Step 2: Check the tools and your balance

Open the Configure Tools button in the chat input. You should see 13 leadocean_ tools. Seven never spend records: count leads, count companies, filter list, enum list, account, get export and list exports.

Ask for your balance before anything else.

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

VS Code docs say you might be asked to confirm each tool call. Confirm the free ones. Read any prompt that names a spending tool before you accept it.

Step 3: Size the audience for free

Write the audience as filters. This example is VP and C-level engineering leaders at software companies with 51 to 200 staff in the UK. Resolve the industry string first, because filters take exact values.

Use leadocean_list_enum_values for industry with q "software". Then use
leadocean_count_leads with jobLevel ["C-Team","VP"], jobFunction ["Engineering"],
industry ["Software Development"], employeeRange ["51-200"], country ["GB"].
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": ["C-Team", "VP"],
    "jobFunction": ["Engineering"],
    "industry": ["Software Development"],
    "employeeRange": ["51-200"],
    "country": ["GB"],
    "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.

Step 4: Spot-check five rows

Look at real rows before you buy 191 of them. Five records is a cheap test of the match. 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.

Step 5: Export the full 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. An export takes up to 50,000 rows a request and 500,000 a day, and each row costs one record. Bulk CSV export is on Solo and above, not on Free. On Free, pull the 191 with leadocean_search_leads in pages of 100 instead.

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

The job runs in the background. Poll every pollAfter seconds, 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

To stay in chat, 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 191, 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 Step 3 run is real. On 1 October 2026 we ran leadocean_list_enum_values and leadocean_count_leads with the filters above. Both are free. This is what the count returned.

{
  "total": 191,
  "totalIsExact": true,
  "credits": 0,
  "defaults": "Counted only addresses worth sending to (emailStatus: verified or catch_all_valid or catch_all)",
  "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. Your number will differ as the data refreshes.

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": "UK engineering leaders at software companies",
    "status": "queued",
    "requested": 191,
    "perRow": "<1, or 2 when a column needs the full record>",
    "remaining": "<records left after this reservation>",
    "pollAfter": 10,
    "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 costs about 196 records: 5 for the spot-check and 191 for the export.

Troubleshooting

FAQ