---
title: MCP 接入
description: 将 Whale 的统一检索与文档读取能力接入支持 Model Context Protocol 的 AI 应用。
---

# 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`。

## 环境变量

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

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

## 构建

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

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

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

## Claude Desktop

在 Claude Desktop 的 MCP 配置中添加：

```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

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

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

## 调用流程

```mermaid
sequenceDiagram
  participant U as 用户
  participant H as MCP Host
  participant M as whale-mcp
  participant W as Whale Data API
  U->>H: 查找指定主题的跨平台内容
  H->>M: tools/call whale_search
  M->>W: POST /v1/contents/search
  W->>W: 校验 Key、订阅、访问策略与限流
  W-->>M: 统一检索结果
  M-->>H: MCP structuredContent
  H-->>U: 带来源的回答
```

## 错误与重试

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

## 安全边界

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