按需查阅，不是必读接入步骤。接入路线：[查询取数接入路线](/docs)

# MCP 接入

使用支持 Streamable HTTP 和 Bearer Header 的 MCP 客户端连接 Whale，无需下载服务端源码。
先取得 [Consumer API Key](/docs/portal)。

## 连接服务

在客户端新增远程 MCP Server：

| 配置 | 值 |
| --- | --- |
| 服务地址 | `https://www.marsyoo.com/mcp` |
| 传输方式 | Streamable HTTP |
| 请求头名称 | `Authorization` |
| 请求头值 | `Bearer <你的 Consumer API Key>` |

通过客户端的安全凭证设置或环境变量注入 Key，不将完整 Key 写入公开配置或对话。
如果客户端不支持授权请求头，改用[查询 SDK（Python 与 Go）](/docs/sdk)或[HTTP API](/docs/quickstart)。

## 验证连接

1. 连接后刷新工具列表，确认出现 `whale_search`。
2. 调用该工具，传入 `{"query":"人工智能","mode":"keyword","limit":10}`。
3. 如果有结果，取其中的 `document_id`，调用 `whale_get_document_content`。

工具正常返回、正文可读取即完成接入。查询结果为空不代表连接失败，先检查关键词和订阅范围。

## 可用工具

| 工具 | 用途 | 主要参数 |
| --- | --- | --- |
| `whale_search` | 关键词、向量或混合查询 | `query`、`mode`、`datasets`、`platforms`、`languages`、`published_from`、`published_to`、`limit` |
| `whale_get_document` | 文档详情与当前版本 | `document_id` |
| `whale_get_document_content` | 当前或指定版本完整正文 | `document_id`、`version_id` |

查询默认 `hybrid`、20 条，最大 100 条。工具权限与直接调用 API 相同，受应用订阅、字段权限和限流约束。

`401` 检查客户端是否发送了正确 Key；`403` 检查应用订阅；`429` 按 `Retry-After` 退避。
参数说明见[关键词与语义检索](/docs/search)，正文与版本见[读取内容与历史](/docs/documents)。

## 继续当前任务

[返回接入路线](/docs)；查完所需信息后，回到正在执行的步骤。