MCP server

The Ocean.io MCP server exposes the API to any AI assistant that speaks the Model Context Protocol. Once connected, your assistant can search companies and people, look up fields and industries, and export CSVs directly from a chat interface — no custom glue code required.

MCP requests consume credits at the same rate as equivalent REST calls. See Credits for per-tool costs.

Prerequisites#

  • An active Ocean.io API token. Create one at Settings → API tokens.
  • An AI assistant that supports MCP (Claude.ai, Claude Desktop, Claude Code, Cursor, and others).

Claude.ai / Claude Desktop (recent)#

Go to Settings → Connectors → Add custom connector and paste:

https://api.ocean.io/mcp/?api-token=YOUR_API_TOKEN

No JSON editing or Node.js required. Custom connectors are tied to your Claude account and sync across Claude apps: add it once on claude.ai and it works in Claude Desktop too, and vice versa.

Claude Code#

From your terminal:

claude mcp add --transport http ocean_data_api https://api.ocean.io/mcp/?api-token=YOUR_API_TOKEN

Restart Claude Code (or refresh the MCP tools) to pick it up.

Claude Desktop (older versions)#

Use this only if your build has no Connectors UI. Unlike connectors, this method runs on your machine and requires Node.js to be installed: without it, Claude Desktop fails silently and the tools never appear. If possible, update Claude Desktop and use the connector method above instead.

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "ocean_data_api": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.ocean.io/mcp/?api-token=YOUR_API_TOKEN"
      ]
    }
  }
}

Quit and reopen Claude Desktop. The Ocean.io tools will appear in the tool picker.

Cursor#

Open Settings → MCP → Add new global server and paste the same JSON as above. Restart Cursor to pick it up.

Available tools#

Tool What it does Cost
list_company_fields Every company field you can filter or request. Static — cache for the session. Free
list_people_fields Every people field. Static. Free
list_industries Ocean.io industry taxonomy. Static. Free
list_linkedin_industries LinkedIn industry filter options. Static. Free
search_companies Filter or lookalike search. Paginated. 0.2 credits / result
search_people Search by title, location, skills, company. Paginated. 0.2 credits / result
export_companies CSV export — up to 10,000 domains. Requires user confirmation. 0.2 credits / exported company
export_people CSV export — up to 10,000 LinkedIn handles or URLs. Requires user confirmation. 0.2 credits / exported person

Export credit examples:

  • 5 companies exported = 1.0 credit
  • 25 companies exported = 5.0 credits
  • 1,000 companies exported = 200 credits

You're only charged for records the export actually returns — failed matches don't count.

Behaviour notes#

  • Reference tools (list_*) are static within a session — cache them to avoid burning turns on lookups.
  • Search results are paginated. Ask the assistant to fetch the next page rather than assuming the first response is complete.
  • Exports require explicit user confirmation in the assistant before they run. Confirm scope and cost first.

Example flow#

Prompt: Find Chicago-headquartered companies similar to pandadoc.com and export them to CSV.

The assistant typically:

  1. Calls search_companies with lookalikeDomains: ["pandadoc.com"] and a Chicago location filter.
  2. Returns the matches (e.g., OneSpan, Mediafly, Conga, Showpad, ActiveCampaign) with a one-line summary of each.
  3. States the export cost (5 × 0.2 = 1.0 credit) and asks for confirmation.
  4. On confirm, calls export_companies and returns the download URL.