MCP 接入

Whale MCP Server 是 Whale Data API 的轻量适配层。它把检索与文档读取转换为 MCP Tools，供 Claude Desktop、Codex 和其他 MCP Host 调用。权限仍由 Whale 应用的 Consumer API Key 决定，MCP 不会绕过订阅、字段范围或限流策略。

可用工具

Tool	作用	主要参数
`whale_search`	统一关键词、向量与混合检索	`query`、`mode`、`dataset_ids`、`source_platforms`、`languages`、`published_from`、`published_to`、`top_k`
`whale_get_document`	按 ID 获取文档主记录和当前版本信息	`document_id`
`whale_get_document_content`	获取当前或指定版本的完整正文	`document_id`、`version_id`

whale_search 默认使用 hybrid，默认返回 20 条，最大返回 100 条。数据集、平台和字段范围仍受应用订阅限制；越权请求会返回 Whale API 的 403。

环境变量

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

API Key 来自 Portal 中对应应用的“密钥”页面。不要把密钥写入仓库、参数或对话内容。MCP Server 只通过环境变量读取密钥，也不会把它写入日志或工具返回。

构建

从 Whale 源码根目录构建本机二进制：

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

首版使用 stdio 传输。MCP Host 在本机启动该进程，因此不需要开放额外公网端口。

Claude Desktop

在 Claude Desktop 的 MCP 配置中添加：

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

在 Codex 的 MCP Server 配置中使用同一二进制和环境变量。配置键名以当前 Codex 客户端版本为准，核心参数如下：

[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"

调用流程

错误与重试

401：API Key 缺失、格式错误或已失效，检查 Host 注入的环境变量。
403：应用未获得请求的数据集、平台或字段权限，不应自动重试。
429：达到应用速率或并发上限，读取 Retry-After 后退避重试。
5xx 或网络超时：可使用带抖动的指数退避重试；不要无限并发重放。
工具错误会以 MCP Tool Error 返回，不会伪装成正常检索结果。

安全边界

每个 MCP 配置应使用对应 Whale 应用自己的 Key。不要让多个客户、组织或生产环境共享同一 Key。Host 能调用的工具不等于拥有全部数据，最终授权始终由 Whale 服务端执行。