> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 querying.ai MCP 服务器连接 AI 智能体

> 为 Claude Code、Codex 或任何 MCP 客户端提供工具，用于查询 AI 引擎、抓取网页、研究提示词和管理 GEO 监测。

querying.ai MCP 服务器以 [Model Context Protocol](https://modelcontextprotocol.io/) 工具的形式提供 API。它与 REST API 使用相同的引擎、队列、结果结构和 API 密钥，并且不会存储你的密钥或任务。

| | |
| - | - |
| 端点 | `https://mcp.querying.ai/mcp` |
| 传输方式 | Streamable HTTP |
| 认证 | `Authorization: Bearer <API key>` |

## 连接客户端

先把密钥放入 `QUERYING_API_KEY` 环境变量。密钥可在 [API 密钥](https://querying.ai/dashboard/keys)页面获取。

**Claude Code**

```bash theme={"theme":"css-variables"}
claude mcp add --transport http querying \
  https://mcp.querying.ai/mcp \
  --header 'Authorization: Bearer ${QUERYING_API_KEY}'
```

请保留单引号。使用双引号时，shell 会立即展开密钥，Claude Code 会把密钥值写入它的配置文件。

**Codex**

添加到 `~/.codex/config.toml`：

```toml theme={"theme":"css-variables"}
[mcp_servers.querying]
url = "https://mcp.querying.ai/mcp"
bearer_token_env_var = "QUERYING_API_KEY"
tool_timeout_sec = 240
```

**mcp.json**

适用于读取 `mcp.json` 文件的客户端：

```json theme={"theme":"css-variables"}
{
  "mcpServers": {
    "querying": {
      "url": "https://mcp.querying.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

其他 Streamable HTTP 客户端只要在每个请求中发送以下请求头即可使用：

```http theme={"theme":"css-variables"}
Authorization: Bearer <API key>
Accept: application/json, text/event-stream
Content-Type: application/json
```

没有 Bearer 请求头的请求返回 `401`。无效密钥会在第一次工具调用时以工具错误的形式报告。

## 工具

提交任务的工具与相同 API 调用的费用一致。只读工具免费。

### 任务与研究

| 工具 | 作用 | 积分 |
| - | - | - |
| `run_prompt` | 向引擎提交提示词并等待结果。 | 该引擎的价格 |
| `submit_prompt` | 提交提示词并立即返回排队中的任务。 | 该引擎的价格 |
| `get_task` | 返回任务状态，结束后返回结果。 | 免费 |
| `scrape_page` | 以 Markdown 读取一个网页或文本 PDF（`WEB_SCRAPE`）并等待结果。 | 每个 URL 1 |
| `read_product` | 读取一个电商商品页面（`COMMERCE_PRODUCT`），等待其价格、库存、图片、详情图、规格和选项。 | 每页 3 |
| `research_prompts` | 查找人们就某个主题向 AI 助手提出的问题，按搜索需求排序，并附带可直接用于 `create_monitor` 的 `monitorSet`。支持 US 和 KR 市场。 | 11 |
| `run_product_lookup` | 向 AI 购物引擎询问一个商品和最多 5 个竞品并等待结果：每个引擎是否展示、卖家、价格、引用的网站，以及购物提示词的回答展示了哪些商品。支持 US 和 KR 市场。 | 每个商品 10，每个购物提示词 5 |
| `get_product_lookup` | 按 id 返回 Product Lookup 结果，可选摘要或完整内容。 | 免费 |

`run_prompt` 和 `submit_prompt` 接受 `taskType`、`prompt`，以及可选的 `country`、`idempotencyKey`、`include` 和 `page`（1 到 10，用于 `GOOGLE_SERP` 和 `NAVER_SERP`）。引擎及其价格请参阅[引擎](/zh/engines/overview.md)，研究输入请参阅 [Prompt Research](/zh/research/prompt-research.md)。

`COMMERCE_SERP` 用 `site` 和 `query` 代替 `prompt`，`limit`（1 到 40）可选；请参阅 [Commerce Search](/zh/engines/commerce-serp.md)。`read_product` 接受 `url`，以及可选的 `country` 和 `idempotencyKey`；请参阅 [Commerce Product](/zh/engines/commerce-product.md)。

`run_product_lookup` 接受 `product`、`country` 以及可选的 `competitors`、`prompts`、`engines` 和 `idempotencyKey`，参见 [Product Lookup](/zh/research/product-lookup.md)。默认返回摘要：每个商品包含展示它的引擎、价格区间、前 10 个卖家和引用网站，以及每个引擎一行对比；每个购物提示词包含各引擎展示或提及的商品。约为完整响应的十分之一。需要所有商品记录、引用页面和任务 id 时，传入 `detail: "full"`。

### GEO 监测

每个监测器工具都用你的密钥发起一次 API 调用，因此所有权、密钥范围和套餐限制与 REST 相同。参见 [GEO 监测](/zh/monitors.md)。

| 工具 | 作用 | 积分 |
| - | - | - |
| `get_monitor_capabilities` | 监测器引擎、每个任务的积分、限制和指标定义。配置监测器前请先调用。 | 免费 |
| `list_monitors` | 你的监测器及其 30 天汇总。 | 免费 |
| `get_monitor` | 单个监测器的旧版详情视图。 | 免费 |
| `create_monitor` | 创建监测器并启动首次运行。每次运行会在每个引擎上为每个提示词、点位和样本各提交一个任务。 | 按运行计费；参见[成本与计划](/zh/monitors.md#成本与计划) |
| `update_monitor` | 修改字段，或通过 `enabled` 暂停和恢复。 | 免费；增加提示词或引擎会提高每次运行的费用 |
| `delete_monitor` | 删除监测器及其评分历史，无法撤销。 | 免费 |
| `run_monitor` | 立即开始一次运行。 | 一次运行的任务费用，与计划运行相同 |
| `get_monitor_analytics` | 提及率和引用率、周期对比、声量份额，以及按引擎和按提示词的明细行。 | 免费 |
| `get_monitor_sources` | 被引用的域名或页面，使用 `nextCursor` 分页。 | 免费 |
| `get_monitor_results` | 评分行；`includeEvidence` 为 true 时附带回答文本和来源。 | 免费 |
| `get_monitor_answer` | 单个回答的 Markdown、来源和评分上下文。 | 免费 |
| `suggest_monitor_prompts` | 根据品牌信息起草提示词建议，不保存任何内容。 | 免费；每小时 30 次，每 20 秒一次 |
| `get_monitor_alerts` | 告警历史以及告警是否处于待触发状态。 | 免费 |
| `test_monitor_alert` | 发送一封测试告警邮件。每个监测器每 5 分钟最多 3 次（`429 RATE_LIMITED`）。 | 免费 |

## 超时

`run_prompt`、`scrape_page`、`read_product` 和 `research_prompts` 会轮询直到任务结束。它们最多等待 `timeoutSeconds`（默认 180，最大 900）。如果任务仍在运行，工具返回带有 `taskId` 的 `TASK_TIMEOUT` 错误。任务会继续运行；用该 id 调用 `get_task` 即可获取结果。

`run_product_lookup` 以同样方式轮询。默认等待 210 秒，以便在 240 秒的客户端超时内结束，多数查询在 2 到 3 分钟内完成。如果查询仍在运行，工具返回带有 `lookupId` 的 `LOOKUP_TIMEOUT` 错误；用该 id 调用 `get_product_lookup`。

请把客户端的工具超时设得比 `timeoutSeconds` 更长。Codex 示例针对默认的 180 秒使用了 `tool_timeout_sec = 240`。如果客户端只允许较短的工具调用，请先用 `submit_prompt`，再用 `get_task`。

## 错误

工具错误以 JSON 形式出现在工具结果中：

| 错误码 | 含义 |
| - | - |
| `KEY_SCOPE_DENIED` 等 API 错误码 | API 拒绝了调用；包含状态和详情。参见[错误](/zh/concepts/errors.md)。 |
| `VALIDATION_ERROR` | 工具输入无效。 |
| `TASK_TIMEOUT` | 任务结束前等待已终止。包含 `taskId`。 |
| `LOOKUP_TIMEOUT` | Product Lookup 的所有询问结束前等待已终止。包含 `lookupId` 和仍在等待的引擎。 |
| `TASK_FAILED` | 任务失败。包含 `taskId` 和任务结果。 |

## 计费

每次工具调用都按与 REST API 相同的价格计入密钥所属账户。密钥设置同样生效：密钥上的[引擎范围或每日积分上限](/zh/authentication.md#密钥设置)会限制智能体可消耗的积分。请为智能体单独分配一个有范围限制和每日上限的密钥。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.