Company Headcount with MCP

Ask Claude or Cursor how big a company is and the agent calls get_company. One URL, OAuth sign-in, 1 record per lookup, a miss is free.

This page is about setup and prompts. For the field list and the REST call, see Company Headcount. To build a list by size instead of looking up one company, see find companies by headcount. Other clients are on the MCP hub.

Connect the server

The server is https://api.leadocean.io/mcp. It signs in with OAuth 2.1, so there is no key to paste. Create a free account first.

Claude Code. The command format is from the Claude Code MCP docs, September 2026:

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

Cursor. Add a remote server to mcp.json, in the url form shown in the Cursor MCP docs, September 2026:

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

Cursor starts the OAuth sign-in the first time the server is used. Other clients use the same URL, see the LeadOcean MCP docs.

The tool

Headcount has no tool of its own. It comes back inside get_company, which the server lists as leadocean_get_company. It costs 1 record per call.

Send one of the two. Name-only lookups do not work, so the agent asks for a domain.

To find companies by size, the agent uses search_companies with employeeRange, or minEmployees and maxEmployees. That costs 1 record per company returned.

Prompts that work

Put the record limit in the prompt. "Stop after 25 records" is enough for the agent to hold a batch.

What the agent gets back

The result is one leadocean.company.v1 object plus a meta block. Headcount sits in company_data.company_employees: number_of_employees, a banded number_of_employees_code, and min and max, per the company docs, September 2026. Below is the response shape, trimmed to the headcount fields, with placeholder values (Acme).

{
  "success": true,
  "data": {
    "company_data": {
      "company_name": "Acme",
      "company_domain": "acme.com",
      "company_employees": {
        "number_of_employees": 250,
        "number_of_employees_code": "201-500"
      },
      "company_linkedin_followers": 12345
    },
    "company_metrics": { "completion_score": 94, "marketability_score": 81 },
    "meta": { "sources": ["own"], "schema": "leadocean.company.v1" }
  },
  "meta": { "credits": 1, "source": "own" }
}

Unknown values are null, never guessed. The band can be present where the exact number is not, so a range filter still works on those records.

A hit with no headcount on file still costs 1 record, because you received a company. A company we hold nothing for is a 404 and costs nothing.

Free checks first

count_leads, list_enum_values and get_account spend no records. Run them before any paid call.

We ran count_leads with employeeRange: ["201-500"] and hqCountry: ["US"] on 2026-10-01. It returned total: 5895665, totalIsExact: true, credits: 0. That counts mailable people (verified, catch_all_valid or catch_all) at those companies, not the companies themselves.

Troubleshooting

FAQ