MCP server

MCP requests use the same credit balance as the platform and the REST API. See Credits for how credits work.

Prerequisites#

• An Ocean.io account. MCP is built for plans with unified credits. Accounts on older plans can connect too, and the costs below show your plan's rates.
• An AI assistant that supports remote MCP servers (Claude, ChatGPT, Claude Code, Cursor, and others).

Authentication#

The server URL is:

https://api.ocean.io/mcp/

There are two ways to authenticate:

• Sign in with Ocean.io (OAuth). Any Ocean.io user can connect. The assistant opens an Ocean.io sign-in page, and you click Allow access. Use this in every assistant that supports it.
• API token. For clients without sign-in support, send a token in the x-api-token header. Only managers can create tokens, at Settings → API tokens.

Claude (claude.ai, Desktop, mobile)#

1. Open Settings → Connectors → Add custom connector.
2. Paste https://api.ocean.io/mcp/, click Add, then Connect.
3. Sign in to Ocean.io and click Allow access.

Custom connectors are tied to your Claude account, so a connector added on claude.ai also works in Claude Desktop and mobile.

ChatGPT#

ChatGPT connects to custom MCP servers on the web. Business and Enterprise/Edu workspaces get every tool; admins and owners add the server, and on Enterprise/Edu an admin can let other members add it. On Pro, a custom server gets read and fetch access only, so searches and lookups work but exports, reveals and other write actions don't.

1. Go to Plugins, select the + button, then Add custom MCP server.
2. Enter Ocean.io as the name and, under Connection, https://api.ocean.io/mcp/ as the URL.
3. Choose OAuth as the authentication.
4. Review the risk warning, select I understand and want to continue, then Create as a plugin.
5. Install the plugin, sign in to Ocean.io, and click Allow access.
6. In a new chat, type @ and select Ocean.io.

Workspaces still on the older Apps page add the server from Settings → Apps → Create instead.

Claude Code#

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

Then run /mcp in Claude Code and sign in to Ocean.io. To use an API token instead:

claude mcp add --transport http ocean https://api.ocean.io/mcp/ --header "x-api-token: YOUR_API_TOKEN"

Cursor#

Open Cursor Settings → MCP → Add new global MCP server and add:

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

Cursor asks you to sign in to Ocean.io. To use an API token instead, add "headers": { "x-api-token": "YOUR_API_TOKEN" } to the ocean entry.

Other clients#

Point the client at https://api.ocean.io/mcp/ over Streamable HTTP. The server supports OAuth discovery and dynamic client registration, so clients that implement the MCP authorization spec can sign in without extra setup. Otherwise, send an API token in the x-api-token header.

Disconnect#

Open Settings → Connected apps and click Disconnect next to the app. Access stops within a minute, and managers can disconnect any app in their organization. Removing Ocean.io inside the assistant ends the connection only if the assistant notifies Ocean.io, so disconnect here to be sure. Sign-ins that go unused for 90 days expire.

Available tools#

Search and look up#

Signals and fit#

Your account#

Contacts and exports#

Workflows#

Reference and feedback#

Export credit examples:

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

On some older plans, each export's total is rounded up to the next whole credit, so exporting one company costs 1 credit.

Ocean.io checks your balance before an export starts. If the balance doesn't cover the whole export, nothing is exported and nothing is charged. Records that fail to export aren't charged.

Behaviour notes#

• Confirmations. Tools that spend credits on exports or reveals, or that change data, are annotated as destructive. Claude and ChatGPT ask you to confirm before they run. Other clients may run them without asking, depending on their settings.
• Check the cost first. count_companies and count_people are free. They return the exact cost of fetching num_results matches, 100 by default and up to 10,000, so set it to the match count to price a whole large search.
• Large searches. search_companies and search_people return a resultSetId that holds the rows of that call: num_results of them, 10 by default and up to 10,000. Export tools accept it as result_set_id in place of a list of domains or person IDs; CRM and webhook exports take up to 1,000 rows. A larger search continues on later pages, fetched by passing the response's searchAfter value as search_after, and each page has its own resultSetId. Result sets expire 30 days after the search. If one can't be saved, the rows still come back without it.
• Not enough credits. Search, CRM export and webhook export errors state how many credits the request needs and how many are available. CSV export errors say only that credits are insufficient. A reveal reveals as many contacts as the balance covers and lists the rest as skipped for lack of credits. Ask for fewer results, or ask an organization manager about the balance.

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 primaryLocations filter.
2. Returns the matches (for example 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 you to confirm.
4. On confirm, calls export_companies and returns the download URL.

CSV download links work for anyone who has the link, so share them only with people who are allowed to see the data.

Privacy#

Ocean.io receives the requests your assistant makes to its tools, not your full conversation. Section 14 of the Privacy Policy describes what Ocean.io stores for assistant connections and for how long.