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

# Didit MCP 工具集与只读模式

> 通过工具集仅加载所需的 Didit MCP 工具，以只读模式连接，并借助工具搜索按需调用其他所有工具。

工具集让 Didit MCP 连接只加载一份简短的工具列表，而不是完整目录；只读模式则让您获得一个永远无法更改数据的连接。两者都通过服务器 URL 上的参数设置：

```text theme={null}
https://mcp.didit.me/mcp?toolsets=core
https://mcp.didit.me/mcp?read_only=true
```

如果不添加参数，服务器会列出您的角色可以使用的所有工具，因此您已有的连接不会有任何变化。

## 为什么要少加载工具

您的客户端会在您提出第一个问题之前，把列出的每个工具的定义发送给模型。
对于完整的 Didit 目录，每个请求都要消耗数万个 token：大约 50,000 到 115,000 个，具体取决于模型的分词器。
有些客户端还会限制可接受的工具数量。

| 连接加载的内容 | 列出的工具 | 这些工具占用的 token 比例 |
| - | - | - |
| 全部（无参数） | 您的角色可使用的每个工具 | 全部 |
| 精简列表 `core` | 约 30 个 | 约十分之一 |
| 精简列表，只读 | 约 20 个 | 不到十分之一 |

这种做法需要多一个步骤。
不在列表中的工具并不会丢失，但模型必须先通过[工具搜索](#获取未加载的工具)找到它，才能运行。看到全部工具的模型，选对工具的概率比需要先搜索的模型略高一些。
当对话跨越多个领域且上下文成本无关紧要时，请加载全部工具。
当上下文成本很重要时，请加载 `core` 以及您最常用的工具集。

## 选择工具集

在服务器 URL 后添加 `toolsets`，并用逗号分隔列出需要的工具集：

```text theme={null}
https://mcp.didit.me/mcp?toolsets=core
https://mcp.didit.me/mcp?toolsets=core,workflows
https://mcp.didit.me/mcp?toolsets=core,transactions,cases
```

`core` 是大多数工作的起点，也就是精简列表。
它涵盖您的组织和应用、验证会话（创建、查找、做出决策、解释、在沙盒中模拟，以及读取 Webhook 投递记录）、查找工作流、分析和余额、应用的 API 密钥和 Webhook、查找案件、用户、企业和交易，以及文档搜索。

* `core`：上面的精简列表。
* `account`：组织、应用、API 密钥、成员和角色。
* `billing`：套餐、额度余额、支付方式、收据和账单信息。
* `sessions`：验证会话（创建、查找、做出决策、审核、分享、导入、PDF 和 Webhook 投递记录）。
* `workflows`：验证工作流和问卷（构建、编辑、校验和发布）。
* `lists`：自定义列表、黑名单和白名单。
* `vendors`：您验证的人员和企业（供应商用户和供应商企业）。
* `transactions`：交易监控（交易、钱包筛查，以及带回测的规则）。
* `cases`：案件管理（创建、分配、升级和解决案件）。
* `investigator`：Investigator（其审核队列、报告、决策、政策问题和绩效）。
* `webhooks`：Webhook 目标和警报。
* `reports`：分析、导出和审计日志。
* `branding`：验证流程的白标品牌设置。
* `verification`：独立验证 API（证件、人脸、AML、地址证明、电话、邮箱、数据库和企业核验）。
* `travel_rule`：Travel Rule（设置、VASP 目录、网络、地址、转账和消息）。
* `marketplace`：服务商市场（目录、您的连接和集成请求）。
* `networks`：欺诈网络（共享同一设备、证件或联系方式的关联会话、用户和企业）。
* `compliance`：合规助手（您的监管档案、其要求，以及据此生成的工作流）。
* `docs`：搜索 Didit 文档。
* `all`：您的角色可以使用的所有工具。这是默认值。

[工具参考](https://docs.didit.me/zh/integration/mcp/tools.md)列出了每个工具及其类型，以及它所需的角色权限。

工具选择的行为如下：

* **工具集是可选的。** 不带 `toolsets` 的 URL 会列出所有工具。
* **指定工具集时，只列出这些工具集中的工具。** `?toolsets=cases` 会列出案件工具，以及每个连接都会获得的 `didit_context_get`。如果还想保留精简列表，请添加 `core`。
* **工具集只决定列出哪些工具，不决定您能运行哪些工具。** 即使某个工具不在您的选择范围内，模型按名称调用时仍可运行，并且仍受与以往相同的角色权限约束。
* **服务器不认识的名称会被忽略。** 连接仍然可用，服务器会告知模型被忽略的名称以及有效的名称。
* **您的角色依然生效。** 工具集从不授予权限：请参阅[角色与权限](https://docs.didit.me/zh/integration/mcp/authentication.md#角色与权限)。

## 以只读模式连接

在服务器 URL 中添加 `read_only=true`：

```text theme={null}
https://mcp.didit.me/mcp?read_only=true
https://mcp.didit.me/mcp?toolsets=core,reports&read_only=true
```

只读连接只会列出用于读取的工具，服务器会拒绝每一次会创建、修改或删除内容的调用。
服务器会针对每次调用执行拒绝，因此即使您的客户端记得之前连接中的某个工具，服务器仍会拒绝该调用。
可将其用于生成报告、探索账户，或用于您不希望其自行执行操作的智能体。

要重新允许进行更改，请在不带 `read_only` 的情况下连接。

## 获取未加载的工具

当连接只加载了工具目录的一部分时，服务器会额外添加四个工具，确保所有工具都可以访问：

* `didit_tool_search`（读取）：按您想做的事情查找工具（例如"将会话导出为 CSV"），或列出某个工具集。每个匹配结果都会说明工具的用途、参数，以及它是读取、写入还是破坏性操作。
* `didit_tool_describe`（读取）：返回最多五个工具的完整描述和输入架构。
* `didit_tool_call_read`（读取）：运行一个不在列表中的只读工具。对于会更改数据的工具，它会拒绝执行。
* `didit_tool_call_write`（破坏性）：运行一个不在列表中、用于创建、修改或删除数据的工具。只读连接中不提供此工具。

通过 `didit_tool_call_read` 或 `didit_tool_call_write` 发起的调用，检查方式与直接调用完全相同：角色权限、只读模式以及所有 `confirm: true` 要求仍然适用。

之所以将两者分开，是为了让您的客户端在更改数据前征求您的同意，同时允许查询操作直接通过。

在已加载 `core` 的情况下，像"邀请一位新团队成员加入我的组织"这样的请求会按以下步骤处理：

1. 模型调用 `didit_tool_search`，搜索 `invite a teammate`，得到标记为写入操作的 `didit_org_invite_member`。
2. 模型调用 `didit_tool_call_write`，将 `didit_org_invite_member` 作为 `name` 传入，并附上该工具自己的参数。
3. 与任何会更改数据的工具一样，您的客户端会请求您批准此次调用。

当所有工具都已加载时，就没有需要发现的内容了，因此不会列出这四个工具。

## 在客户端中进行设置

步骤与[安装指南](https://docs.didit.me/zh/integration/mcp/installation.md)相同，只是在 URL 中加上参数。

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http didit "https://mcp.didit.me/mcp?toolsets=core"
> ```
>
> 保留引号：否则 shell 会自行解析 `?` 和 `&`。

> [tab] Codex
>
> ```bash theme={null}
> codex mcp add didit --url "https://mcp.didit.me/mcp?toolsets=core"
> ```

> [tab] Cursor
>
> 在 `~/.cursor/mcp.json` 中：
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "didit": {
>       "url": "https://mcp.didit.me/mcp?toolsets=core"
>     }
>   }
> }
> ```

> [tab] VS Code
>
> 在 `.vscode/mcp.json` 中：
>
> ```json theme={null}
> {
>   "servers": {
>     "didit": {
>       "type": "http",
>       "url": "https://mcp.didit.me/mcp?toolsets=core"
>     }
>   }
> }
> ```

> [tab] Claude 网页版和桌面版
>
> 依次打开 **Settings**、**Connectors**，然后点击 **Add custom connector**，并粘贴带参数的 URL：
>
> ```text theme={null}
> https://mcp.didit.me/mcp?toolsets=core
> ```

> [tab] 本地服务器
>
> 本地服务器接受命令行参数或环境变量：
>
> ```bash theme={null}
> npx -y @didit-protocol/mcp-server --toolsets=core,workflows --read-only
> ```
>
> ```bash theme={null}
> DIDIT_TOOLSETS=core,workflows DIDIT_READ_ONLY=true npx -y @didit-protocol/mcp-server
> ```

如果您的客户端允许设置请求头，但不能编辑 URL，请改为发送 `X-MCP-Toolsets: core,workflows` 和 `X-MCP-Readonly: true`。
对于工具集，URL 中的值优先于请求头；只要 URL 或请求头中任一方要求开启，只读模式即会启用。

> [!NOTE]
>
> ChatGPT 插件使用其固定的精简目录，地址为 `https://mcp.didit.me/mcp/chatgpt`。
> 工具集和只读模式不适用于该插件。
> 请参阅[连接 ChatGPT](https://docs.didit.me/zh/integration/mcp/chatgpt.md)。

## 提示词、指令与文档搜索

服务器帮助模型从正确的起点开始：

* **指令。** 连接时，服务器会告诉模型先调用 `didit_context_get`，说明 `organization_id` 和 `application_id` 如何解析，在沙盒应用中进行构建，以及此连接加载了哪些工具集。
* **提示词。** 支持 MCP 提示词的客户端会显示五个起点：`integrate_didit`、`review_queue`、`explain_session`、`build_workflow` 和 `verification_report`。在 Claude Code 中，它们会以斜杠命令的形式出现。
* **文档搜索。** `didit_docs_search` 会搜索这些文档，并返回匹配章节及其链接，因此有关 Didit 工作原理的问题都可以根据当前页面来回答。

## 检查连接已加载的内容

向您的客户端提问：

```text theme={null}
Which Didit toolsets does this connection load, and is it read-only?
```

模型会根据服务器的指令作答。
在依赖工具集之前，若要确认服务器支持工具集，请读取其健康检查 endpoint：

```bash theme={null}
curl https://mcp.didit.me/healthz
```

响应在 `features` 下列出 `toolsets` 和 `read_only`。

## 下一步

> [card] [安装](https://docs.didit.me/zh/integration/mcp/installation.md)
>
> 连接 Claude、ChatGPT、Cursor、VS Code、Codex 或任何 MCP 客户端。

> [card] [工具参考](https://docs.didit.me/zh/integration/mcp/tools.md)
>
> 每个工具、其类型以及所需的角色权限。

> [card] [身份验证](https://docs.didit.me/zh/integration/mcp/authentication.md)
>
> 使用 Didit 登录，以及权限范围和角色权限。

> [card] [示例提示词](https://docs.didit.me/zh/integration/mcp/examples.md)
>
> 第一天即可使用的提示词。


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