How to Research an Account Before a Call in Codex CLI

TL;DR

• Codex CLI reaches LeadOcean through one codex mcp add command and a browser sign-in. It can then pull a company, its buying group and one contact, and draft a call brief.
• It takes about 15 minutes the first time and about 5 after that. The example account spends about 11 of your 1,000 free records.
• Counts, filter lookups and enum lookups cost nothing. Only people and companies returned count, one record each.

Prerequisites

• A LeadOcean account from app.leadocean.io. The free plan has no card and 1,000 records, one-off.
• Codex CLI installed and signed in. The Codex MCP docs, September 2026, cover how servers are added and managed.
• The account's domain, such as acme.com, and the name or LinkedIn URL of the person you are meeting.
• Optional, for the REST versions: 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. Server details are on the LeadOcean MCP page.

Step 1: Add the LeadOcean MCP server

Run one command. The Codex docs show codex mcp add taking a --url for a remote server.

codex mcp add leadocean --url https://api.leadocean.io/mcp
codex mcp login leadocean

The second command starts the OAuth sign-in in your browser. LeadOcean uses OAuth 2.1, so you paste no key. The server supports dynamic client registration at https://api.leadocean.io/oauth/register, which Codex can use to register itself.

The command writes a table to ~/.codex/config.toml. You can write it by hand instead, or scope it to one project in .codex/config.toml (trusted projects only).

[mcp_servers.leadocean]
url = "https://api.leadocean.io/mcp"

Start codex, then type /mcp. You should see leadocean with 13 tools.

Step 2: Block the tools that spend records

Research needs only the free tools plus a few paid ones. The Codex docs describe an enabled_tools allow list per server. Use it to keep an exploratory prompt from spending records you did not plan.

[mcp_servers.leadocean]
url = "https://api.leadocean.io/mcp"
enabled_tools = [
  "leadocean_count_leads",
  "leadocean_list_filters",
  "leadocean_list_enum_values",
  "leadocean_get_company",
  "leadocean_search_leads",
  "leadocean_get_lead",
]

This list leaves out leadocean_export_leads, leadocean_search_companies and leadocean_find_phone. Add leadocean_count_companies too if you size company lists; it is free. Tool names are the ones the server reports. Check them in /mcp before you rely on the list.

Step 3: Size the buying group for free

Count before you pull anyone. This example uses VPs and C-level people at one company.

Use leadocean_count_leads with domain ["acme.com"] and jobLevel ["C-Team","VP"].
Pass 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 '{"domain": ["acme.com"], "jobLevel": ["C-Team", "VP"], "limit": 1}' | jq '.meta'

If the total is 0, check the domain spelling before you assume nobody is there. Counting is free however often you ask.

Step 4: Pull the company

One company lookup costs one record. It gives you the firmographics for the first line of the brief.

Use leadocean_get_company with domain "acme.com". Give me industry, headcount,
HQ country, funding and detected technologies in six lines. Pass slim false so
the technology list comes back. Do not search people yet.

The REST route is POST /v1/companies/enrich with a domain.

curl -s https://api.leadocean.io/v1/companies/enrich \
  -H "x-api-key: $LEADOCEAN_API_KEY" -H "content-type: application/json" \
  -d '{"domain": "acme.com"}' | jq '.data | keys'

A company we hold nothing for returns a 404.

Step 5: Pull the buying group

Use the same filters and email statuses as the count, so the number you pay for matches the number you sized.

Use leadocean_search_leads with domain ["acme.com"], jobLevel ["C-Team","VP"],
emailStatus ["verified","catch_all_valid","catch_all"] and limit 10. Show a table of
name, job title, job function and email_status. Group it by function.

Each person returned costs one record. The REST body is flat JSON with arrays for filters and a limit of 1 to 100.

curl -s https://api.leadocean.io/v1/people/search \
  -H "x-api-key: $LEADOCEAN_API_KEY" -H "content-type: application/json" \
  -d '{
    "domain": ["acme.com"],
    "jobLevel": ["C-Team", "VP"],
    "emailStatus": ["verified", "catch_all_valid", "catch_all"],
    "limit": 10
  }' | jq '.data | length, .meta.nextCursor'

To see everyone we hold at the company, use GET /v1/companies/{domain}/people. It pages with a cursor, stops at 10,000 rows and bills one record per person.

Step 6: Enrich the person you are meeting

Pick the contact from the table. Enrich by person_id, or by a LinkedIn URL or email if you already have one.

Use leadocean_get_lead with the person_id of the VP of Sales from the table above.
Return the email, email_status, any phone numbers held and their last three roles
from the career history. Then stop.

The REST call takes exactly one of linkedin_url, email, phone or person_id. Set reveal_email to true to get the address.

curl -s https://api.leadocean.io/v1/people/enrich \
  -H "x-api-key: $LEADOCEAN_API_KEY" -H "content-type: application/json" \
  -d '{"person_id": "<person_id from search>", "reveal_email": true}' | jq '.data.contact_data'

Revealing the email costs no extra record. Since October 2026 the same answer carries career history in resume_data: past roles with titles, companies and dates, plus education and certifications when we hold them. Past employers carry no company_id yet. A person we hold nothing for is a 404 and costs nothing. For numbers alone, GET /v2/people/phone takes the same identity, and a v2 call that finds nothing still costs one record.

Step 7: Write the call brief

This step needs no tool calls. The data is already in the session, so Codex only writes.

Using only the company, the table and the contact above, write a one-page call brief:
1. Who they are, in two lines.
2. Who is likely in the buying group, by function.
3. Three questions for the person I am meeting.
4. One thing I could not confirm from this data.
Do not invent funding, news or numbers. Do not call any more tools.

The last line matters. The data holds role, past roles, company, headcount and contact status. It does not hold news or call notes, so Codex should say so rather than fill the gap.

What you get

The Step 3 count comes back as a small JSON object from the free count tool. To show a real one without naming a real account, we ran the same filters one level up on 2026-10-21. The segment is C-Team and VP people in the US at Software Development companies of 201 to 500 staff. It cost 0 records.

{
  "total": 15800,
  "totalIsExact": true,
  "totalAll": 36424,
  "distinctCompanies": 1683,
  "distinctCompaniesIsExact": true,
  "credits": 0,
  "hasMore": true,
  "unsupportedFilters": []
}

total is the mailable count: people whose best email is verified, catch_all_valid or catch_all. totalAll is the same filters with no email condition. distinctCompanies says those 15,800 people work at 1,683 companies, which is a list of accounts to research. The credits field is the tool's own name for what the call spent. Run Step 3 with your account's domain and you get the same fields for one company.

The enrich call returns the person's contact block. This is the response shape from the API reference, with placeholder values.

{
  "success": true,
  "data": {
    "contact_data": {
      "has_email": true,
      "has_phone": true,
      "email_status": "verified",
      "contact_emails": [{ "email": "jane.doe@acme.com", "type": "work", "status": "verified" }],
      "contact_phones": [{ "phone": "+14155550133", "type": "direct" }]
    }
  },
}

The run spends about 11 records: 1 for the company, 9 for the people and 1 for the contact. Read email_status before you send anything. A bounce is not refunded.

Troubleshooting

FAQ