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

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:

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

{
  "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:

[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

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.