---
title: MCP Integration
description: Connect Whale search and document retrieval to AI applications that support Model Context Protocol.
---

# MCP Integration

Whale MCP Server is a thin adapter over the Whale Data API. It exposes retrieval and document reads as MCP tools for Claude Desktop, Codex, and other MCP hosts. Authorization still comes from the application's Whale Consumer API Key. MCP never bypasses subscriptions, field scope, or rate limits.

## Available Tools

| Tool | Purpose | Main inputs |
| --- | --- | --- |
| `whale_search` | Keyword, vector, or hybrid search through one contract | `query`, `mode`, `dataset_ids`, `source_platforms`, `languages`, `published_from`, `published_to`, `top_k` |
| `whale_get_document` | Load document metadata and current version by ID | `document_id` |
| `whale_get_document_content` | Load full content for the current or a specific version | `document_id`, `version_id` |

`whale_search` defaults to `hybrid` and 20 results, with a maximum of 100. Dataset, platform, and field scope remain limited by the application's subscription. Out-of-scope requests return `403` from the Whale API.

## Environment

```bash
export WHALE_API_BASE_URL="https://whale.xinzhiaigc.com"
export WHALE_API_KEY="whale_consumer_your_application_key"
```

Create the key from the application's Keys page in Portal. Never commit it or include it in arguments or conversations. The MCP server reads the key only from the environment and never logs or returns it.

## Build

Build the local binary from the Whale repository root:

```bash
go build -o ./bin/whale-mcp ./cmd/whale-mcp
```

The first release uses `stdio`. The MCP host starts the process locally, so no additional public port is required.

## Claude Desktop

```json
{
  "mcpServers": {
    "whale": {
      "command": "/absolute/path/to/whale-mcp",
      "env": {
        "WHALE_API_BASE_URL": "https://whale.xinzhiaigc.com",
        "WHALE_API_KEY": "whale_consumer_your_application_key"
      }
    }
  }
}
```

## Codex

Use the same binary and environment in the MCP server configuration for the installed Codex version:

```toml
[mcp_servers.whale]
command = "/absolute/path/to/whale-mcp"

[mcp_servers.whale.env]
WHALE_API_BASE_URL = "https://whale.xinzhiaigc.com"
WHALE_API_KEY = "whale_consumer_your_application_key"
```

## Request Flow

```mermaid
sequenceDiagram
  participant U as User
  participant H as MCP Host
  participant M as whale-mcp
  participant W as Whale Data API
  U->>H: Find cross-platform content
  H->>M: tools/call whale_search
  M->>W: POST /v1/contents/search
  W->>W: Authorize key, subscription, policy, and rate
  W-->>M: Normalized search response
  M-->>H: MCP structuredContent
  H-->>U: Grounded answer
```

## Errors and Retries

- `401`: the key is missing, malformed, or expired. Check the host environment.
- `403`: the application is not entitled to the requested scope. Do not retry automatically.
- `429`: rate or concurrency limit reached. Back off according to `Retry-After`.
- `5xx` or network timeout: retry with jittered exponential backoff and bounded concurrency.
- Tool failures are returned as MCP Tool Errors rather than normal search results.

## Security Boundary

Each MCP configuration should use the key for its own Whale application. Never share one key across customers, organizations, or production environments. A tool being visible to a host does not grant unrestricted data access; Whale always makes the final authorization decision.