Add LeadOcean to Codex's config.toml, sign in once, and Codex can count, search and enrich people and companies from the terminal or the IDE extension. The free plan gets the same server as Agency.
This page covers Codex only. ChatGPT on the web and the ChatGPT desktop app are on their own page, and other clients are on the MCP hub.
Before you start
You need a LeadOcean account and Codex installed. Create a free account. It has no card and 1,000 records, one-off, and it needs a work email.
Add the server
The server URL is https://api.leadocean.io/mcp. It speaks Streamable HTTP. Add it to ~/.codex/config.toml:
[mcp_servers.leadocean]
url = "https://api.leadocean.io/mcp"Codex reads the file at start, so restart Codex after you save it.
Sign in: option A, OAuth
Run this once from the shell:
codex mcp login leadoceanYour browser opens on LeadOcean. Sign in, approve, and return to the terminal. No API key is pasted anywhere. You do not register an OAuth client yourself: the LeadOcean OAuth server supports dynamic client registration at https://api.leadocean.io/oauth/register (scope mcp).
To revoke, run codex mcp logout leadocean, or remove the app under API keys, Connected apps in your LeadOcean account.
Sign in: option B, an API key
Use this instead of option A, not both, where no browser is available, such as a server, CI or a container. Create a key just for Codex under API keys, put it in an environment variable, and point Codex at that variable:
[mcp_servers.leadocean]
url = "https://api.leadocean.io/mcp"
bearer_token_env_var = "LEADOCEAN_API_KEY"export LEADOCEAN_API_KEY="lo_live_..."Codex sends the key as Authorization: Bearer .... The key spends the same records as the API and keeps its own limits, so pausing or revoking it stops Codex straight away. Keep the key in the environment, not in the config file you share.
Your first prompt
Start with a count. Counting is free.
How many VP-level sales leaders in the UK can I email? Count only. Do not pull anyone.
Codex calls leadocean_count_leads with jobLevel set to VP, jobFunction set to Sales & Business Development and country set to GB. That costs 0 records. We ran the same filters on 2026-10-01 and the tool returned 3,146, an exact total.
That figure is mailable people only: email status verified, catch_all_valid or catch_all. When the count looks right, ask for five people with title and company. That calls leadocean_search_leads at 1 record per person, so 5.
The 15 tools
Codex lists them as leadocean_ plus the name below. Nine of them spend no records.
| Tool | What it does | Records |
|---|---|---|
leadocean_count_leads | Counts people for a filter set. | Free |
leadocean_count_companies | Counts companies for a filter set, with breakdowns by industry, size, HQ country, HQ state and NAICS. | Free |
leadocean_list_filters | Lists valid filters and enum values. | Free |
leadocean_list_enum_values | Looks up exact strings, such as one of 534 industries. | Free |
leadocean_get_account | Shows plan, records left and export ceilings. | Free |
leadocean_get_export | Polls one export for status and download link. | Free |
leadocean_list_exports | Lists your exports. | Free |
leadocean_mark_viewed | Remembers people as already shown, so later searches, counts and exports can leave them out. | Free |
leadocean_clear_viewed | Removes people from a viewed list, or clears the list. | Free |
leadocean_search_leads | Finds people by title, level, country, domain and more. | 1 per person returned |
leadocean_get_lead | Enriches one person by LinkedIn URL, email or person_id. | 1 |
leadocean_find_phone | Returns the phone numbers held for one person. | 1 |
leadocean_get_company | Enriches one company by domain or LinkedIn URL. | 1 |
leadocean_search_companies | Finds companies by industry, size, funding or technology. | 1 per company returned |
leadocean_export_leads | Starts a bulk CSV export of people. | 1 per row |
A leadocean_get_lead call that finds nobody costs nothing. Source: LeadOcean MCP docs, November 2026.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
leadocean not listed | Codex was not restarted, or the TOML table name is wrong. | Check [mcp_servers.leadocean] and restart Codex. Run codex mcp list. |
| Asks to log in every time | The OAuth sign-in never finished. | Run codex mcp login leadocean again and approve in the browser. |
| 401 with an API key | The variable is empty in the shell Codex runs in, or the key is revoked or paused. | Run echo $LEADOCEAN_API_KEY in that shell, and check the key under API keys. |
| 402 | Your 1,000 free records are spent, or an export needs more than you have left. | Check leadocean_get_account. Move to Agency at $497 a month, or shrink the limit. |
| 429 | Past your plan's rate limit, or an export ceiling. | Wait a second and retry, or ask for smaller batches. |
FAQ
OAuth or API key?
Use OAuth on your own machine: no secret is stored. Use an API key where no browser can open. Both spend the same records from one balance as the REST API.
Is the free plan the same server as Agency?
Yes. Free is 1,000 records, one-off. Agency is $497 a month, flat, with no per-record price.
Connect Codex to 996M people, free
Free to start. No credit card. 1,000 records to spend whenever you like.
Get your free API key →