How to Search a B2B Database from Claude (MCP Server Setup)

A B2B database MCP server lets an AI client search companies and people with typed tool calls instead of a pasted CSV. This guide connects LeadOcean's hosted server, sizes a list for free, then pulls a handful of records.

TL;DR

• Add one URL (https://api.leadocean.io/mcp) as a remote MCP server and sign in with OAuth 2.1. No key is pasted.
• Setup takes about 10 minutes. Sizing calls (leadocean_count_leads, leadocean_count_companies) cost 0 records.
• The walkthrough spends about 5 records, one per person in the sample. The Free plan has 1,000 records for life.

Prerequisites

• A LeadOcean account. Free is $0, no card, 1,000 records for life, 5 requests a second (pricing).
• An MCP client that supports remote servers with OAuth. Claude is the example here.
• Optional for the REST fallback in Step 5: an API key from app.leadocean.io, exported as $LEADOCEAN_API_KEY.

Step 1: Add the server

Point your client at the hosted endpoint. In Claude Code it is one command (Claude Code MCP docs):

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

Other clients take the same URL as a remote MCP server. Per-client steps are on the MCP setup page.

On first use the client opens a sign-in window (OAuth 2.1). The server also supports dynamic client registration at https://api.leadocean.io/oauth/register, so clients can register themselves.

Step 2: Check the 13 tools and which ones cost records

Ask the model to list what it can call. Seven tools are free. The rest spend one record per person or company returned.

Rule of thumb: count first, search second. A count never spends a record, however many times you ask.

Step 3: Resolve filter values before you search

Enum filters are exact strings. A wrong value returns nothing, so resolve it first. Prompt:

Use leadocean_list_enum_values for job_level, then for industry with q="software".

The job levels come back as C-Team, Director, Manager, Other, Staff and VP. Industry has 534 values and country has 254, so search them with q instead of guessing.

Step 4: Size the list, then pull a sample

Size the audience for free. Prompt:

Count VPs in Sales & Business Development in Canada. Facets off.

The model calls leadocean_count_leads with jobLevel: ["VP"], jobFunction: ["Sales & Business Development"], country: ["CA"]. Then count companies:

How many software companies headquartered in Germany have 51-200 employees?

That calls leadocean_count_companies with industry: ["Software Development"], hqCountry: ["DE"], employeeRange: ["51-200"]. When the number looks right, pull a small sample:

Search the same Canadian VPs, limit 5. Show title, company and email status.

Keep limit small while you test. Five people is five records.

Step 5: Run the same query over REST

The search tools map to REST endpoints, so you can move a working query into code. The flat JSON body takes arrays for filters, a limit from 1 to 100, and a cursor for the next page.

curl -s -X POST https://api.leadocean.io/v1/people/search \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jobLevel": ["VP"],
    "jobFunction": ["Sales & Business Development"],
    "country": ["CA"],
    "limit": 5
  }'

For a free count over REST, send count=true as a query parameter with limit=1. It does not go in the JSON body, which rejects unknown fields.

curl -s -X POST "https://api.leadocean.io/v1/people/search?count=true" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jobLevel": ["VP"], "country": ["CA"], "limit": 1}'

meta.total is capped at 100,000. One search pages up to 10,000 rows, then meta.depthCapped is true. Narrow the filters instead of walking the index.

What you get

Real output from leadocean_count_leads, run on 21 October 2026 with jobLevel VP, jobFunction Sales & Business Development, country CA:

{
  "total": 5574,
  "totalIsExact": true,
  "totalAll": 18800,
  "distinctCompanies": 3873,
  "credits": 0,
  "defaults": "Counted only addresses worth sending to (emailStatus: verified or catch_all_valid or catch_all)"
}

Read it carefully. total is the mailable count (verified, catch_all_valid or catch_all). totalAll is the same filters with no email condition. credits: 0 confirms the call was free.

Real output from leadocean_count_companies, same date, industry Software Development, hqCountry DE, employeeRange 51-200 (top states shown):

{
  "total": 738,
  "totalIsExact": true,
  "facets": {
    "hq_state": [
      {"value": "Bavaria", "count": 101},
      {"value": "North Rhine-Westphalia", "count": 75},
      {"value": "Berlin", "count": 57}
    ]
  },
  "credits": 0
}

Pick the industry label with care. The older Computer Software label is a separate value and matches far fewer companies.

A search returns records. The shape below is the response shape from the API reference, with placeholder values:

{
  "success": true,
  "data": [
    {
      "profile_data": {
        "profile_full_name": "Jane Doe",
        "profile_headline": "VP Sales at Acme"
      },
      "contact_data": {
        "has_email": true,
        "email_status": "verified",
        "email_type": "work",
        "contact_current_experiences": [
          { "company_name": "Acme", "company_domain": "acme.com", "job_title": "VP Sales" }
        ]
      },
      "meta": { "source_ids": { "person_id": "1234567890" } }
    }
  ],
  "meta": { "count": 5, "credits": 5, "nextCursor": null }
}

Search rows carry email flags, not addresses. leadocean_get_lead (or POST /v1/people/enrich with reveal_email) returns the address for 1 record.

Troubleshooting

FAQ