> For the complete documentation index, see [llms.txt](https://docs.goassay.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.goassay.ai/developers/zh/can-kao/mcp-tools.md).

# MCP 工具

查阅 Assay MCP 工具的参数、返回数据和错误。

智能体看到的工具取决于登录状态、连接的 MCP URL 和访问策略。Assay 在托管服务器上提供三个发现和调用工具。本地 `assay-mcp` 在断开连接时还提供登录。下方工具名为客户端添加服务器前缀之前的 MCP 名称。较长的目录名称可能以本地别名列出；其说明会标明原始 Assay 名称。

## 会列出什么

| 连接状态或模式    | 显示的工具                                                      |
| ---------- | ---------------------------------------------------------- |
| 本地 MCP，未登录 | `assay_sign_in`。                                           |
| 完整发现       | 此 URL 和智能体有权访问且可列出的目录工具。                                   |
| 搜索发现       | 最多五个可访问的固定目录工具，以及 `search_tools`、`get_tool` 和 `call_tool`。 |
| 自动发现       | 按 URL 的阈值和可访问工具数量选择完整或搜索发现。                                |

即使完整发现未列出这三个托管工具，在限定范围的 URL 上仍可调用。它们不能扩大该 URL 和智能体的访问范围。见 [URL 与配置文件](/developers/zh/shi-yong-gong-ju-jin-jie/urls-and-profiles.md)和[访问策略](/developers/zh/shi-yong-gong-ju-jin-jie/access-policy.md)。

## `assay_sign_in`

将本地 MCP 连接到 Assay 账户。这是本地辅助工具，不是托管目录工具。

| 项目       | 契约                                                  |
| -------- | --------------------------------------------------- |
| 输入       | 空对象：`{}`。无声明参数。                                     |
| 输出       | 文本，含批准链接和返回客户端的说明。首次登录会打开批准页面。                      |
| 已登录      | 返回 `Assay is connected. Its tools are listed here.` |
| 登录结束或过期  | 返回终端登录命令，以及可用时可自行打开的链接。不会自动重新打开页面。                  |
| 其他窗口正在登录 | 文本提示你到另一个窗口批准。                                      |
| 失败       | 开始登录时，可能因密钥链、锁或登录设置失败返回 JSON-RPC 错误。                |
| 收费       | 无。                                                  |

有链接不代表批准已完成。登录完成后才会出现工具；必要时重启客户端。批准步骤见[安装 assay-mcp](/developers/zh/shi-yong-gong-ju-ru-men/install-assay-mcp.md)，设置故障见[故障排查](/developers/zh/shi-yong-gong-ju-jin-jie/troubleshooting.md)。

## `search_tools`

按用途查找工具。这是免费读取，不会调用提供方。

| 输入         | 必填               | 含义和限制                                                                   |
| ---------- | ---------------- | ----------------------------------------------------------------------- |
| `query`    | 未提供 `cursor` 时必填 | 字符串；控制字符转为空格后，最多 500 个字符和 1,500 个 UTF-8 字节。接受空字符串。                      |
| `category` | 否                | 分类字符串；转为小写；最多 64 个字符。                                                   |
| `detail`   | 否                | `names`、`summary`（默认）或 `full`。                                          |
| `limit`    | 否                | 整数；names 默认 10，summary 默认 5，full 默认 3。大于 50 时限制为 50；小于 1 时使用对应详情级别的默认值。 |
| `cursor`   | 否                | 上次响应的 `nextCursor`。延续原来的查询、分类、详情级别和条数限制。                                |

拒绝额外输入属性。使用游标时，由保存的搜索控制分页；其他传入字段不会重新定义搜索。

| 输出             | 含义                                                                               |
| -------------- | -------------------------------------------------------------------------------- |
| `results`      | 排序后的匹配项。所有详情级别都包含 `name` 和 `score`；`notReviewed: true` 可标记尚未审核的提供方工具。            |
| 摘要结果字段         | `summary`、`version`、`kind`、显示用的 `price`、结构化 `assayPrice` 和 `freeCallsLeftToday`。 |
| 完整结果字段         | 摘要字段加 `inputSchema`。过大时，`inputSchemaOmitted` 和 `note` 会说明如何通过 `get_tool` 读取。     |
| `categories`   | 此发现响应限定目录范围内可访问的分类。                                                              |
| `total`        | 排序匹配项总数，不只是当前页。                                                                  |
| `nextCursor`   | 继续分页的字符串或 `null`。                                                                |
| `limitApplied` | 实际应用的请求页大小；字节上限可能进一步减少实际结果数。                                                     |

结果同时以 `structuredContent` 和 `content` 中的 JSON 文本返回。响应上限为 256 KiB。游标绑定凭据和规范化 URL，在第一页之后 10 分钟过期，最多 10 页。每页都会重新检查访问权限。

| 错误                       | 含义和处理方式                                                  |
| ------------------------ | -------------------------------------------------------- |
| `TOOL_ARGUMENTS_INVALID` | 参数结构错误、无游标时缺少查询，或超过文本限制。请修正输入。                           |
| `INVALID_CURSOR`         | 分页信息过期、改变或不匹配。请重新搜索。                                     |
| `RATE_LIMITED`           | 达到搜索限制：每个智能体跨 URL 每个固定 UTC 分钟最多 30 次。请等待 `retryAfterMs`。 |

## `get_tool`

读取一个工具的完整契约和当前价格。同样免费。

| 项目    | 契约                                                                                                              |
| ----- | --------------------------------------------------------------------------------------------------------------- |
| 输入    | 必填 `name` 字符串。不允许额外属性。                                                                                          |
| 身份和说明 | `name`、`kind`、`category`、`tags`、`summary`、`description`，以及可选的 `notReviewed`。                                    |
| 输入和输出 | `inputSchema`、`outputSchema`、`optionalInputFields`、`optionalOutputFields`、`examples`。                           |
| 版本    | `version`、可选 `changelog`，以及适用的 `assay/deprecated` 元数据（`sunsetAt` 和 `replacement`）和提供方工具元数据。这是通过此 URL 调用时会使用的版本。 |
| 价格和供应 | `tier`、结构化 `price` 或 `null`、`noProviderFits`、`freeCallsLeftToday`、`annotations`。                                |
| 输出封装  | `structuredContent` 和 `content` 中的 JSON 文本。                                                                     |
| 收费    | 无。                                                                                                              |

| 错误                       | 含义和处理方式                                                   |
| ------------------------ | --------------------------------------------------------- |
| `TOOL_ARGUMENTS_INVALID` | 名称缺失、输入类型错误或有额外属性。请修正输入。                                  |
| `TOOL_NOT_IN_TOOLSET`    | 在此 URL 和访问范围内不可用、名称未知，或没有可列出的供应。请在目标连接上重新搜索。              |
| `RATE_LIMITED`           | 达到读取限制：每个智能体跨 URL 每个固定 UTC 分钟最多 120 次。请等待 `retryAfterMs`。 |

## `call_tool`

读取契约后，按名称运行工具。调用采用所选工具的价格；此包装工具不另收发现费用。

| 输入          | 必填 | 含义                           |
| ----------- | -- | ---------------------------- |
| `name`      | 是  | 目录工具名称。内层调用不能是发现工具。          |
| `arguments` | 否  | 符合该工具输入 schema 的对象。默认为 `{}`。 |

不接受额外包装属性。付款和幂等元数据应放在 MCP 请求的 `_meta` 中，与 `name`、`arguments` 同级，位于工具参数之外。相同元数据也会应用于内层调用。

| 输出                              | 含义                                                                                                                    |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `content` 和 `structuredContent` | 所选工具的结果，包装工具原样返回。                                                                                                     |
| `_meta["assay/receipt"]`        | `intentId`、含资产和显示值的 `charged` 与 `held` 金额、`status`、`toolId`、`providerId`、`classification`、`attempts`，以及可选 `fellBack`。 |
| `_meta["assay/replayed"]`       | 幂等重放时为 `true`。首次响应时不存在。                                                                                               |
| `isError: true`                 | 工具或平台拒绝。请阅读下方共享错误字段。                                                                                                  |

结果可能以 `VERIFYING` 状态和暂扣金额返回。`SETTLED` 是服务判定，不是提供方已收款的确认。见[一次付费调用的全过程](/developers/zh/di-ceng-yuan-li/life-of-a-call.md)和[结算与保留期](/developers/zh/di-ceng-yuan-li/settlement.md)。

常见错误为 `TOOL_ARGUMENTS_INVALID`、`TOOL_NOT_IN_TOOLSET`、`TOOL_NOT_ALLOWED`、`NO_PROVIDER_MATCHES_RULES`、`PAYMENT_REQUIRED` 和 `PAYMENT_DEBT_OUTSTANDING`。下方共享错误及本地签名拒绝也适用。设置见[付费流程](/developers/zh/shi-yong-gong-ju-ru-men/how-paying-works.md)；重试结果不明的付费调用前，请阅读[重试与幂等](/developers/zh/shi-yong-gong-ju-jin-jie/retries-and-idempotency.md)。

## 直接调用目录工具

每个直接列出的工具都有自己的名称、说明、`inputSchema`，以及声明时的 `outputSchema`。请阅读该描述或 `get_tool`；所有提供方工具并不共用固定参数或结果结构。直接调用和通过 `call_tool` 调用同一工具，使用相同的访问、付款、幂等和收据处理。

这些工具随目录和连接而变化，不是额外的固定 Assay 账户管理工具。上方四个具名 Assay 辅助工具就是已实现的辅助工具集。

## 示例

以下是 MCP `tools/call` 请求的 `params` 对象。此搜索和读取示例不会购买调用。第二个请求请使用搜索返回的实际名称。

```json
{"name":"search_tools","arguments":{"query":"weather","detail":"names","limit":3}}
```

```json
{"name":"get_tool","arguments":{"name":"get_weather"}}
```

## 共享错误和元数据

工具失败通常使用 `isError: true`、`content` 中可读的文本，以及 `_meta["assay/error"]`。错误包含 `code` 和 `retryable`；视原因也可能包含 `message`、`retryAfterMs` 或 `retryAfter`（秒）、`fixUrl`、`callId`、`intentId` 或结构化 `details`。付款要求还会出现在 `_meta["x402/paymentRequired"]`。

| 代码或类别                                                                        | 含义                         | 下一步处理                                                                                               |
| ---------------------------------------------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------- |
| `MCP_URL_NOT_FOUND`（**No MCP server at this URL**）                           | URL 不存在，或此连接无法使用。          | 在 [URL 与配置文件](/developers/zh/shi-yong-gong-ju-jin-jie/urls-and-profiles.md)中检查路径、版本和分享状态。           |
| `MCP_CREDENTIAL_INVALID`                                                     | 凭据缺失或无效。                   | 为目标配置文件重新登录。                                                                                        |
| `MCP_AUTH_RATE_LIMITED`                                                      | 凭据失败尝试过多。                  | 修正登录问题，然后等待一段时间再重试。                                                                                 |
| `TOOL_NOT_IN_TOOLSET`、`TOOL_NOT_ALLOWED`                                     | URL 范围或访问权限拒绝调用。           | 使用目标 URL，并在[访问策略](/developers/zh/shi-yong-gong-ju-jin-jie/access-policy.md)中检查智能体访问权限。              |
| `TOOL_REMOVED`、`CONTRACT_VERSION_RETIRED`                                    | 工具或所选契约版本已不再提供。            | 阅读返回的详情，重新发现工具。                                                                                     |
| `UNSUPPORTED_INPUT_FIELD`                                                    | 没有所需的提供方支持某个可选输入。          | 阅读工具契约，合适时移除不支持的字段。                                                                                 |
| `NO_PROVIDER_MATCHES_RULES`、`TOOL_NO_ELIGIBLE_BINDING`                       | 没有剩余的合格提供方。                | 检查规则或选择其他工具。                                                                                        |
| `TOOL_ALL_BINDINGS_FAILED`                                                   | 对合格提供方的尝试均失败。              | 查看拒绝信息，仅在合适时重试。                                                                                     |
| `TOOL_ARGUMENTS_INVALID`                                                     | 输入不符合声明的 schema。           | 修正后再重试。                                                                                             |
| `INVALID_CURSOR`（**This search expired. Search again.**）                     | 搜索游标已过期、已变更，或属于其他 URL 或连接。 | 重新开始搜索。                                                                                             |
| `RATE_LIMITED`                                                               | 达到发现或被拒调用的限制。              | 按返回的重试间隔等待。                                                                                         |
| `PAYMENT_REQUIRED`                                                           | 此调用需要签名付款许可。               | 本地 `assay-mcp` 会在批准并通过防护后处理签名。                                                                      |
| `PAYMENT_DEBT_OUTSTANDING`                                                   | 先前已提供服务的调用仍有欠款。            | 在 Assay 应用的充值流程中结清。                                                                                 |
| `PAYMENT_INSUFFICIENT_FUNDS`                                                 | 托管余额不足以支付此调用。              | 充值并确认到账后再重试。                                                                                        |
| `PAYMENT_NO_SETTLEABLE_CHAIN`                                                | 调用无法在客户当前网络结算。             | 阅读返回的付款详情，使用兼容且有资金的连接。                                                                              |
| `MCP_QUOTA_EXCEEDED`                                                         | 免费额度已用尽。                   | 等待重置，或在可用时使用返回的付费选项。                                                                                |
| `MCP_SPEND_LIMIT_EXCEEDED`、`MCP_POLICY_AGENT_PAUSED`、`MCP_APPROVAL_REQUIRED` | 智能体支出策略拒绝调用。               | 请所有者检查上限、暂停状态或批准阈值。                                                                                 |
| `MCP_VELOCITY_LIMIT_EXCEEDED`                                                | 触发调用速率、支出速率或重复请求规则。        | 等待恢复间隔。提高本地上限无济于事。                                                                                  |
| `PROVIDER_REQUEST_ERROR`                                                     | 端点拒绝映射后的请求。                | 修正输入或调查映射。                                                                                          |
| `PROVIDER_SYSTEM_ERROR`                                                      | 提供方或平台执行失败。                | 重试前阅读返回的原因。                                                                                         |
| `PROVIDER_CONTRACT_VIOLATION`                                                | 提供方输出违反承诺的结构。              | 阅读退款和调用详情。                                                                                          |
| `IDEMPOTENCY_KEY_REUSED`                                                     | 此键已对应其他操作。                 | 只为相同工具和参数复用键。                                                                                       |
| `IDEMPOTENCY_IN_PROGRESS`                                                    | 之前的尝试仍在运行。此次重试没有收费。        | 等待 `retryAfter` 秒，然后用相同键重试。                                                                         |
| `IDEMPOTENCY_ATTEMPT_STALLED`、`IDEMPOTENCY_RESULT_UNAVAILABLE`               | 先前尝试停滞，或结果无法重放。            | 创建另一笔购买前，先核对现有调用。                                                                                   |
| `MCP_IDEMPOTENCY_KEY_INVALID`                                                | 直接服务器请求中的幂等元数据格式错误。        | 按重试指南使用有效键。                                                                                         |
| `INTERNAL_SERVER_ERROR`                                                      | 服务器发生意外故障。                 | 重试时保留同一逻辑调用的键。                                                                                      |
| 本地付款拒绝（**Assay asked for a payment this app refused: …**）                    | `assay-mcp` 拒绝签名。          | 在[故障排查](/developers/zh/shi-yong-gong-ju-jin-jie/troubleshooting.md)的“付款拒绝”部分查找原因。修改服务器访问权限不会改变本地限额。 |

付款、额度和支出策略拒绝可能带有更多领域代码和恢复字段。请按返回的原因和[故障排查表](/developers/zh/shi-yong-gong-ju-jin-jie/troubleshooting.md)处理。拒绝限流器允许每个智能体在每个固定 UTC 分钟内有 60 次被拒调用，之后调用会被限流。`tools/list` 是 MCP 方法，不是工具；其限制为每个凭据和 URL 每分钟 60 次，受限时报告 JSON-RPC 错误（`-32029`）。身份认证和传输失败也可能发生在工具结果之外。

## 延伸阅读

* [访问策略](/developers/zh/shi-yong-gong-ju-jin-jie/access-policy.md)
* [重试与幂等](/developers/zh/shi-yong-gong-ju-jin-jie/retries-and-idempotency.md)
* [智能合约](/developers/zh/can-kao/smart-contracts.md)

## 下一步

你已读完开发者参考部分。返回[开发者文档](/developers/zh/readme.md)选择集成主题。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.goassay.ai/developers/zh/can-kao/mcp-tools.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.