> ## 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 高级指南：涵盖角色与权限、跨应用行为、托管目录、分支工作流、Webhook、传输细节、故障排除和自托管。 ## 权限范围与角色权限 该连接器在 `didit:management` 和 `didit:verification` 两个权限范围下运行。还有第三个范围 `didit:staff`，虽然会被宣传，但仅对 Didit 员工账户有效。每次调用都会强制执行这两层边界：token 携带您授权的范围，**在这些范围之内，您的控制台角色决定您能做什么**。实际访问权限是两者的交集，因此即使是 `OWNER`，若只授权了 `didit:verification`，管理功能也仍然不可访问。 每个工具对应一项后端权限（`read:sessions`、`write:workflows`、`delete:lists` 等；[工具参考](https://docs.didit.me/zh/integration/mcp/tools.md) 按工具列出了对应权限）。服务器会使用 token 内省返回的组织权限预先检查该权限，检查行为由 `MCP_PERMISSION_MODE` 控制： | 模式 | 行为 | | - | - | | `shadow`（默认） | 列出所有工具；角色无权执行的调用仍会发送到后端，由后端返回 `403`。该判定记录在服务器的审计日志中。 | | `enforce` | 角色无权运行的工具不会出现在 `tools/list` 中；调用此类工具会返回 `missing_scope` 错误，并注明所缺的权限。 | | `off` | 不进行预先检查。 | MCP 从不会超出您的角色权限。某个工具返回 `403` 表示您的角色缺少该权限，并不代表整个连接失败。 *** ## 跨应用与组织解析 Didit 管理 API 按应用划分范围（`/organization/{org}/application/{app}/…`）。MCP 会为您解析范围： * **单个组织和应用**：自动解析，您无需传递任何 ID。 * **多个应用**：跨应用工具（`didit_session_search`、`didit_transaction_search`、`didit_case_search`、`didit_vendor_user_search`、`didit_vendor_business_search`、`didit_workflow_search`、`didit_analytics`）一次调用即可汇总**全部**应用的数据，每行都带有其 `organization_id` / `application_id` 标签。 * 按应用列出的工具（`didit_session_list`、`didit_transaction_list`、`didit_case_list`、`didit_vendor_user_list`、`didit_vendor_business_list`、`didit_workflow_list`）在您未指定应用时会**自动覆盖所有应用**，因此即使您有多个应用，直接说“列出我的会话”也能正常工作。传入 `organization_id` 和 `application_id` 可将范围缩小到单个应用。 使用 `didit_context_get` 可在一次调用中查看您的所有组织和应用（及其 ID）。它还会报告每个应用的 `mode`（`live` 或 `sandbox`），因此切勿根据应用名称猜测运行环境。`didit_session_create` 在沙盒应用上接受 `sandbox_scenario` 参数，用于不计费的测试运行。 *** ## 托管目录包含哪些内容 托管连接器为您提供 **169 个工具**。它还列出了 17 个 Investigator 工具，这些工具仅在您的组织启用 Investigator 后才可使用。另外两个工具，`didit_org_top_up`（Stripe 结账）和 `didit_org_reveal_application_api_key`（原始密钥），会从每个通过 OAuth 认证的调用方的 `tools/list` 中隐藏。五个账户设置工具（`didit_account_*`）完全不包含在远程服务器中，并且在远程服务器上拒绝运行，因为远程连接器绝不能将凭据作为工具参数传入。本地 stdio 服务器保留全部工具，共 193 个。 每个列出的工具都带有 MCP 注解（`readOnlyHint`、`destructiveHint`、`openWorldHint` 和 `title`）以及 `outputSchema`，还有一个 `_meta["anthropic/toolGroup"]` 标签，用于标明其所属领域（会话、工作流与问卷、交易（AML）等）。Claude 等客户端利用这些注解，将连接器的工具划分为只读、写入和破坏性三组。 ## 分支工作流 简单的工作流是功能的扁平列表。对于**条件逻辑**（例如在某个状态下拒绝、根据提取的字段进行路由、依据匹配结果控制某一步骤、添加 Document AI 请求），MCP 会驱动 Didit 的**节点图**（与控制台可视化构建器使用的结构相同）。节点图的形式为 `{ start_node, nodes }`，每个节点可以是 `feature`、`branch`、`status`（终止）、`action` 或 `webhook`。分支规则支持多种运算符，包括**`fuzzy_match`**（用于字符串字段，带有取值 0–100 的 `score` 相似度阈值），可作用于 `kyc.extra_fields.profession` 等已提取的字段。`DOCUMENT_AI` 功能节点用于请求证件（例如资金证明）。 ### 编辑现有工作流（推荐） 实际工作流通常包含**大型**功能配置。例如，OCR 的 `documents_allowed` 允许列表可能达到 150 KB+，另外还有地址证明列表和电话国家列表。因此，**请勿**读取整个图再整体重新提交。应使用少量**操作**进行编辑： **1. 定位并检查** `didit_workflow_search { workflow_id }` 可在您的所有应用中查找该工作流。`didit_workflow_get_graph` 返回结构，其中大型配置会被**汇总**（因此不会超出长度限制；传入 `include_config: true` 可获取原始值）。`didit_workflow_get_field_definitions` 列出可用于分支的字段及其有效运算符。 **2. 使用操作编辑** `didit_workflow_edit_graph` 接受少量操作，包括 `set_next`、`set_node`、`set_branches` 和 `merge_node_config`。MCP 会在服务端获取**完整图**，应用这些操作，进行验证，自动创建**草稿**并保存。您的允许列表会被逐字节保留，且从不经过请求传输。验证失败时会返回 `applied: false`，此时不会保存任何内容。 **3. 审核并发布** 在您通过 `publish` 发布之前（可在控制台中操作，或使用 `didit_workflow_publish`），它始终是可供审核的草稿。线上版本永远不会被修改。 例如，要在身份证件验证后插入一个**重新汇入现有流程**的分支，您只需发送以下内容：将 OCR 节点的 `next` 重新指向新分支，并添加该分支、一个终止的 `Declined` 节点，以及一个 `DOCUMENT_AI` 步骤（其 `next` 指回原来的下一步）。其余 10 个节点及其允许列表均保持不变。 > *"身份证件验证后，若结果为已拒绝，则予以拒绝；若 profession ≈ 'Software Engineer'（≥80%），则请求资金证明；然后继续。"* → 一个 `branch` 节点：`kyc.status == Declined` → 一个 `Declined` 状态节点；`kyc.extra_fields.profession` `fuzzy_match` "Software Engineer" score 80 → 一个 `DOCUMENT_AI` 资金证明节点 → 以及一条返回流程的**否则**路径。 > [!NOTE] > > **分支必须始终包含明确的否则分支。** 兜底路径（即没有任何条件匹配时所走的路径）必须是 `rules` 为空的分支，例如 `{ "id": "else", "rules": [], "goto": "" }`，而不能使用分支节点本身的 `next`。MCP（以及后端）会自动将分支节点的 `next` 转换为否则分支，因此分支不会以没有可见否则的模糊连线形式呈现。 要从头构建新工作流，请使用 `didit_workflow_validate_graph`，然后使用 `didit_workflow_set_graph`（完整图）；也可以让 `didit_workflow_build_graph` 根据纯功能规格组装完整图，且不保存。即使是普通的 `didit_workflow_create`，也会以相同的节点图形式保存：MCP 会将您的 `features` 列表组装成链式功能节点，并以自动决策的状态节点结束，因此这些功能确实会运行（默认会发布；传入 `status: "draft"` 可保持未发布状态）。完整的 JSON 结构请参阅 [创建工作流 → 分支与基于节点的工作流](https://docs.didit.me/zh/management-api/workflows/create.md)。 ### 使用 MCP 处理 NFC 跳过原因分支 对于新图，请这样提问： > *"创建一个草稿工作流，先进行身份证件验证，然后进行 NFC。若 `nfc.skip_reason` 为 `DEVICE_WITHOUT_NFC` 或 `DOCUMENT_WITHOUT_CHIP`，则将会话转入审核中；否则予以已通过。保留明确的否则分支，并在保存前验证节点图。"* 代理应依次调用 `didit_workflow_get_field_definitions`、`didit_workflow_validate_graph`，然后调用 `didit_workflow_set_graph`。对于现有工作流，请这样提问： > *"编辑工作流 `26d33c04…`：在其 NFC 节点之后，将七个已知 `nfc.skip_reason` 值中的任意一个路由到审核中，并将现有的 NFC 成功路径保留为明确的否则分支。保存草稿；不要发布。"* 代理应依次调用 `didit_workflow_search`、`didit_workflow_get_graph`、`didit_workflow_get_field_definitions`，然后调用 `didit_workflow_edit_graph`。编辑工具会在服务端应用少量操作，因此会保留无关节点和大型允许列表。关于七个值、`equals`/`in` 规则、空值行为以及完整有序图，请参阅 [创建工作流 → 根据 NFC 未运行原因进行分支](https://docs.didit.me/zh/management-api/workflows/create.md#根据-nfc-未执行的原因进行分支)。 ### 功能配置与允许列表 功能节点的 `config` 会限制其接受的内容。`didit_workflow_get_feature_config_schema` 会返回每个功能接受的所有键，包括类型和默认值。两个目录工具（`didit_workflow_get_id_verification_methods_catalog` 和 `didit_workflow_get_kyb_registry_catalog`）负责回答配置所依赖的、由服务端决定的问题。规范的 OCR 允许列表结构为按国家、再按证件、最后是对象：`{ "": { "": { "enabled": 1 } } }`（例如 `{ "ESP": { "P": { "enabled": 1 } } }`）。MCP 会在验证前**规范化更友好的写法**，因此您无需手写该结构： | 您可以传入 | 规范化为 | | - | - | | 证件类型数组，例如 `["PASSPORT"]` | 该证件适用于**每个**国家（全球仅限护照） | | 证件**名称**或**代码**，例如 `PASSPORT`/`P`、`NATIONAL_ID`/`ID`、`DRIVER_LICENSE`/`DL`、`RESIDENCE_PERMIT`/`RP`（也包括 `SSC`、`HIC`、`TC`） | 规范代码 | | `"ALL"` 国家键，例如 `{ "ALL": { "P": 1 } }` | 应用于每个国家 | | 标量标志，例如 `{ "ESP": { "P": 1 } }` | `{ "ESP": { "P": { "enabled": 1 } } }` | | 完全省略 | 所有证件、所有国家 | `PROOF_OF_ADDRESS` 的 `poa_languages_allowed` 原理相同：您可以传入语言数组（`["es"]`），也可以传入映射（`{ "es": 1 }`）。这些便捷写法适用于您为 MCP 提供功能配置的任何地方：`didit_workflow_create` 的 features，以及 `set_graph`、`edit_graph`、`validate_graph` 中的节点 `config`。 ## 响应结构 (V3 契约) 每个工具都会原样返回底层 REST endpoint 的 JSON。需要了解以下两点： * **同步工具**（工作流、计费、独立的 `verify_*`、列表管理）会直接内联返回最终结果，同一轮对话中即可据此操作。 * **会话创建是异步的**：`didit_session_create` 会返回一个用户必须完成的 `url`，决策结果通过 Webhook 或 `didit_session_get_decision` 获取。 决策字段**始终为复数数组**，每个条目都带有 `node_id`（`id_verifications[]`、`liveness_checks[]`、`face_matches[]`、`aml_screenings[]`、`poa_verifications[]`、`phone_verifications[]`、`email_verifications[]`、`database_validations[]`、`reviews[]`，以及 KYB 的 `registry_checks[]`、`document_verifications[]`、`key_people_checks[]`）。参见[数据模型](https://docs.didit.me/zh/reference/data-models.md)和[验证状态](https://docs.didit.me/zh/integration/verification-statuses.md)。 *** ## 处理 Webhook 让 Webhook 将最终决策投递到你的后端，而不是由 Agent 轮询： 1. Agent 只需调用一次 `didit_webhook_create`，传入 `label`、你的公网 HTTPS `url`、`webhook_version: "v3"` 以及 `subscribed_events`（通常为 `["status.updated", "data.updated"]`）。响应会隐藏签名密钥，`didit_webhook_get` 和 `didit_webhook_list` 同样如此；请从控制台的 **Webhook** 页面复制该密钥，并将其保存为 `DIDIT_WEBHOOK_SECRET`。 2. 你的后端需在每次投递时验证规范化的 **X-Signature-V2** 请求头：`shortenFloats` → `sortKeys` → `JSON.stringify`（不转义 unicode）→ HMAC-SHA256 → `timingSafeEqual`。若 `abs(now − X-Timestamp) > 300`（秒），则拒绝该请求。 3. 根据 `event_id` 去重。在 **5 秒** 内返回 `2xx`，并将耗时较长的工作放入队列。 4. Didit 在收到 `5xx` 或 `404` 时最多重试 **2 次**（约 1 分钟后一次，再约 4 分钟后一次），之后丢弃该投递。请在控制台的 **投递** 标签页中重放失败的投递。 Agent 只需要*接入*接收端，它本身不会监听。完整契约：[Webhook](https://docs.didit.me/zh/integration/webhooks.md)。 *** ## 传输与 endpoint | endpoint | 用途 | | - | - | | `POST https://mcp.didit.me/mcp` | MCP endpoint（Streamable HTTP）。`GET` 和 `DELETE` 返回 `405`：服务器是无状态的，每个请求都会创建一个新的服务器实例，不保留服务器发起的流或会话，因此无需拆除任何会话。 | | `GET https://mcp.didit.me/healthz` | 健康检查：`{ "status": "ok", "service": "didit-mcp-server", "version": "5.1.1" }`。 | | `GET https://mcp.didit.me/.well-known/oauth-protected-resource/mcp` | RFC 9728 受保护资源元数据（同时在源站根路径提供）。 | 该 endpoint 同时支持两种模式：在每条消息中都固定使用 2026-07-28 或更高协议版本的客户端会跳过 `initialize` 握手，并可调用 `server/discover`；所有更早的客户端（Claude Code、Cursor、基于 SDK 的客户端）则继续使用标准的 Streamable HTTP 握手，无需任何改动。CORS 已开放，因此基于浏览器的客户端（Claude 网页连接器、MCP Inspector）可以跨域访问 `/mcp` 和发现文档。JSON 请求体上限为 25 MB，足以容纳 15 MB 的 base64 文件输入。 *** ## 故障排查 > [accordion] Agent 调用工具时返回 403 或 missing\_scope > > 该组织中你的 **角色** 缺少该工具所需的权限（例如 `READER` 尝试执行写入操作）；`missing_scope` 错误会指明缺少的权限。若所有工具都失败，请重新连接或重新执行*Log in with Didit*。（MCP 仅支持 Bearer/OAuth：`x-api-key` 会被所有工具拒绝，因此使用 API 密钥也无法解决 403 问题。） > [accordion] 写入或删除操作未执行 > > 破坏性工具需要在客户端中确认。请批准该调用，或检查工具的确认提示是否被自动拒绝。`didit_session_delete`、`didit_session_batch_delete` 和 `didit_org_reveal_application_api_key` 还需要在工具参数中包含 `confirm: true`；否则调用会在执行前被拒绝。 > [accordion] 'organization\_id is required' 或无结果 > > 你可能有多个应用。请使用 `*_search` 工具（可跨所有资源搜索），或运行 `didit_context_get`，并传入你需要的 `organization_id` / `application_id`。 > [accordion] 托管模式下浏览器未打开登录页面 > > 部分客户端（Windsurf、Zed）通过 `mcp-remote` 桥接器连接，请确保配置中包含 `npx -y mcp-remote@latest https://mcp.didit.me/mcp`。重新打开客户端以重新触发 OAuth 握手。 > [accordion] 工具未出现在客户端中 > > 请确认服务器已连接（大多数客户端会显示状态指示点），并且已完成*Log in with Didit*。修改配置后请重启 MCP 宿主。`didit_org_top_up` 和 `didit_org_reveal_application_api_key` 在托管连接器上从不会列出。 > [accordion] VS Code（或其他客户端）无法发现 OAuth / 从不打开浏览器 > > 请确保指向 `https://mcp.didit.me/mcp`，而不是裸的 `https://mcp.didit.me` 源站地址。资源元数据提供于 `/.well-known/oauth-protected-resource/mcp`，仅限该路径（同时在源根路径保留一份副本，供在源站根路径探测的客户端使用）。如果你自行部署，这通常意味着 `MCP_RESOURCE_URI` 被设置为源站地址，而不是完整的传输 URL；参见[自托管部署](#自托管)。 > [accordion] 文件上传被拒绝 > > 对于托管 endpoint，请以 `*_base64` 形式发送文件（原始 base64 或 `data:` URL）；`*_path` 仅在本地 stdio 服务器上可用。文件上限为 15 MB，且必须依据内容而非仅依据扩展名为 PNG、JPG、WebP、GIF、BMP、ICO 或 PDF 格式。 *** ## 安全 MCP 以你的真实权限运行，并且可以修改生产环境中的实时资源。请在客户端中保持启用 **"review tool calls before running"**，尤其是对 **Write** 和 **Destructive** 工具。MCP 本身不会在你的配置中存储**任何密钥**（它使用 **Didit 登录**），会在工具输出中隐藏 API 密钥和 Webhook 签名密钥，在托管目录中隐藏充值工具和原始密钥工具，并且在远程服务器上绝不接受把账户凭据作为工具参数。每次工具调用都会写入服务器的审计日志，记录调用方、工具和权限判定结果。 ### 提示词注入 Didit 工具会返回你的用户输入或上传的内容，例如姓名、证件文本和问卷答案。 被验证的人可以控制这些文本，因此他们可以在姓名或证件中写入针对你的智能体的指令，而服务器会按照采集时的原样返回这些字段。 智能体无法可靠地区分这些文本与你自己的指令，因此请把每个工具结果都视为数据： * 对 **Write** 和 **Destructive** 工具保持开启工具审批，并在批准前阅读智能体即将执行的操作。 * 以其角色符合工作要求的成员身份登录。只读取会话的智能体可以使用 `READER` 成员，无论智能体如何尝试，后端都会拒绝其写入。 * 先在[沙盒应用](https://docs.didit.me/zh/integration/sandbox-testing.md)上测试新的智能体或提示词。 * 绝不要因为某次验证中的文本这样要求，就批准或拒绝该验证。请依据决策、其中的警告以及你自己的审核。 ### 个人数据 工具结果可能包含个人数据，例如姓名、出生日期、证件号码以及图片链接，而你的 MCP 客户端会将这些数据发送给它所使用的模型。 在连接生产环境应用之前，请确认你与 AI 提供商的协议涵盖这些数据，或者改用沙盒应用进行测试。 *** ## 自托管 托管服务器由 [github.com/didit-protocol/mcp](https://github.com/didit-protocol/mcp)（MIT）构建。克隆该仓库，然后使用 **Docker** 或 Node 运行。无论采用哪种传输方式，它始终以 Didit **用户**身份进行认证（不存在 API 密钥模式）。安装步骤见 [安装 → 自托管](https://docs.didit.me/zh/integration/mcp/installation.md#自托管)。 ```bash theme={null} git clone https://github.com/didit-protocol/mcp.git && cd mcp # Docker (recommended) — serves /mcp + /healthz on port 3000 docker build -t didit-mcp . && docker run -p 3000:3000 --env-file .env didit-mcp # …or with Node npm install && npm run build node dist/http.js # hosted HTTP/OAuth DIDIT_ACCESS_TOKEN= node dist/index.js # stdio (headless) ``` ### 环境变量 | 变量 | 模式 | 用途 | | - | - | - | | `DIDIT_ACCESS_TOKEN` | stdio | 用于无头运行的用户 Bearer 访问令牌。 | | `DIDIT_API_BASE_URL` | 两种 | 验证 API 基础地址（默认 `https://verification.didit.me/v3`）。 | | `DIDIT_AUTH_BASE_URL` | 两种 | 认证 API 基础地址（默认 `https://apx.didit.me/auth/v2`）。 | | `MCP_PORT` | 托管 | HTTP 监听端口（默认 `3000`）。 | | `MCP_RESOURCE_URI` | 托管 | 传输的公开 URL，包含路径（例如 `https://mcp.example.com/mcp`）。RFC 9728 元数据 URL 由它派生。 | | `MCP_AUTHORIZATION_SERVER_ORIGIN` | 托管 | 授权服务器的源（默认 `https://business.didit.me`）。 | | `MCP_TOKEN_VERIFY_MODE` | 托管 | `introspection`（默认；不透明令牌）或 `jwks`（JWT 访问令牌）。 | | `MCP_OAUTH_INTROSPECT_URL` | 托管 | RFC 7662 令牌内省端点。 | | `MCP_OAUTH_CLIENT_ID` / `MCP_OAUTH_CLIENT_SECRET` | 托管 | 资源服务器调用内省端点时使用的 Basic 认证凭据。请从密钥管理器中提供。 | | `MCP_SCOPES_SUPPORTED` | 托管 | 元数据中公布的作用域（默认 `didit:management didit:verification`）。 | | `MCP_DEFAULT_ORG` / `MCP_DEFAULT_APP` | 两种 | 为单租户部署自动填充作用域。 | | `DIDIT_AUTH_ISSUER`、`DIDIT_OIDC_DISCOVERY_URL`、`DIDIT_OIDC_AUTHORIZE_URL`、`DIDIT_OIDC_TOKEN_URL`、`DIDIT_OIDC_REGISTRATION_URL` | 托管 | 覆盖授权服务器的元数据；仅当其端点发布在不同于该源默认地址的位置时才需要。 | | `DIDIT_JWKS_URL` | 托管 | 当 `MCP_TOKEN_VERIFY_MODE=jwks` 时使用的 JWKS。 | | `MCP_PERMISSION_MODE` | 两种 | 每个工具的权限预检查：`shadow`（默认）、`enforce` 或 `off`。 | | `MCP_JSON_BODY_LIMIT` | 托管 | JSON-RPC 请求体大小限制（默认 `25mb`）。 | 仓库中的 `.env.example` 是可直接复制的模板，`ARCHITECTURE.md` 说明了资源服务器与授权服务器的拆分方式。启动时，HTTP 服务器会获取授权服务器的发现文档；如果无法访问，则回退到已配置的 URL。 *** > [card] [工具参考](https://docs.didit.me/zh/integration/mcp/tools.md) > > 按领域分组的所有工具。 > [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.