Connect LeadOcean MCP to Claude Code

Run one claude mcp add command, sign in through your browser, and Claude Code can search, count and enrich people and companies. No API key is pasted anywhere. The free plan gets the same server as Pro.

This page covers Claude Code only. Other clients are on the MCP hub, including VS Code and Claude.

Before you start

You need two things: a LeadOcean account and Claude Code installed. Create a free account. It has no card and 1,000 records, one-off, and it needs a work email.

The Claude Code MCP docs, September 2026, name no paid plan for adding a remote HTTP server. Your own organization may restrict MCP servers through managed settings, so ask your admin if the add step is refused.

Add the server

The server URL is https://api.leadocean.io/mcp. Claude Code recommends the HTTP transport for remote servers, so use --transport http:

bash

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

Run claude mcp list to check it. A fresh server shows ! Needs authentication until you sign in.

The command saves to local scope by default, which means the current project only. Add --scope user to load it in every project, or --scope project to write it to a shared .mcp.json. Do not add a --header "Authorization: ..." flag. Claude Code docs say a rejected header is reported as a failed connection, with no fallback to OAuth.

Sign-in is OAuth 2.1 in your browser. Start Claude Code, run /mcp, pick leadocean and choose to authenticate. Or run this from the shell:

bash

claude mcp login leadocean

Your browser opens on LeadOcean. Sign in, approve, and return to the terminal. The tools appear without a restart.

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), and Claude Code registers itself.

Over SSH there is no local browser. claude mcp login leadocean --no-browser prints the URL. Open it on your own machine, then paste the full redirect URL back at the prompt.

To revoke, choose "Clear authentication" in /mcp or run claude mcp logout leadocean. You can also remove the app under API keys, Connected apps in your LeadOcean account.

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.

Claude Code 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. It is not everyone we hold for those filters.

When the count looks right, ask for a sample: "Pull five of them with title and company." That calls leadocean_search_leads and costs 1 record per person returned, so 5. For a bigger sizing exercise, see size your TAM in Claude Code.

The 12 tools

Claude Code lists them as leadocean_ plus the name below. Six of them spend no records.

Tool	What it does	Records
`leadocean_count_leads`	Counts people for a filter set.	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_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. Exports reserve up to your limit when they start, so count first. Source: LeadOcean MCP docs, September 2026.

Troubleshooting

Symptom	Cause	Fix
`claude mcp list` shows `✘ Failed to connect`	Wrong URL, wrong transport or no network path.	Run `claude mcp get leadocean` for the Issue line. Remove the server and re-add it with `--transport http` and the exact URL.
`already exists in local config`	The name `leadocean` is taken at that scope.	Run `claude mcp remove leadocean`, then add again.
Status stays `! Needs authentication`	The OAuth window was closed before you approved.	Run `/mcp` or `claude mcp login leadocean` again. If the redirect fails, paste the callback URL into the prompt.
402	Your 1,000 free records are spent, or an export needs more than you have left. The free plan is one-off.	Check `leadocean_get_account`. Move to Pro at $499 a month, or shrink the `limit`.
429	Past the rate limit of 100 requests per second per key, or an export ceiling was reached.	Wait a second and retry, or ask the agent to work in small batches. Export 429s return a reset time.
503 `no_source`	Search was briefly unavailable.	Retry with backoff. Counts and lookups cost nothing while it is down.
Wrong enum, filter rejected	A value is not in the catalogue, such as an invented industry.	Have the agent call `leadocean_list_enum_values` and use the exact string it returns.

FAQ

Do I need an API key for Claude Code?

No. The MCP server uses OAuth sign-in. The REST API uses an x-api-key header. Both spend the same records from one balance.

Is the free plan the same server as Pro?

Yes. Free is 1,000 records, one-off, with search and enrich both available. Pro is $499 a month, flat, with no per-record price.

What does the agent cost me per prompt?

Only records it receives. Counts, filter lookups and account checks are free. Tell it a limit, such as "stop after 25 records", and it will hold to it.

Connect Claude Code to 693M people, free

Free to start. No credit card. 1,000 records to spend whenever you like.

Get your free API key →