Didit MCP 高级配置、故障排除与自托管

权限范围与角色权限

该连接器在 didit:management 和 didit:verification 两个权限范围下运行。还有第三个范围 didit:staff，虽然会被宣传，但仅对 Didit 员工账户有效。每次调用都会强制执行这两层边界：token 携带您授权的范围，在这些范围之内，您的控制台角色决定您能做什么。实际访问权限是两者的交集，因此即使是 OWNER，若只授权了 didit:verification，管理功能也仍然不可访问。每个工具对应一项后端权限（read:sessions、write:workflows、delete:lists 等；工具参考按工具列出了对应权限）。服务器会使用 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+，另外还有地址证明列表和电话国家列表。因此，请勿读取整个图再整体重新提交。应使用少量操作进行编辑：

定位并检查

didit_workflow_search { workflow_id } 可在您的所有应用中查找该工作流。didit_workflow_get_graph 返回结构，其中大型配置会被汇总（因此不会超出长度限制；传入 include_config: true 可获取原始值）。didit_workflow_get_field_definitions 列出可用于分支的字段及其有效运算符。

使用操作编辑

didit_workflow_edit_graph 接受少量操作，包括 set_next、set_node、set_branches 和 merge_node_config。MCP 会在服务端获取完整图，应用这些操作，进行验证，自动创建草稿并保存。您的允许列表会被逐字节保留，且从不经过请求传输。验证失败时会返回 applied: false，此时不会保存任何内容。

审核并发布

在您通过 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 资金证明节点 → 以及一条返回流程的否则路径。

分支必须始终包含明确的否则分支。 兜底路径（即没有任何条件匹配时所走的路径）必须是 rules 为空的分支，例如 { "id": "else", "rules": [], "goto": "<liveness>" }，而不能使用分支节点本身的 next。MCP（以及后端）会自动将分支节点的 next 转换为否则分支，因此分支不会以没有可见否则的模糊连线形式呈现。

要从头构建新工作流，请使用 didit_workflow_validate_graph，然后使用 didit_workflow_set_graph（完整图）；也可以让 didit_workflow_build_graph 根据纯功能规格组装完整图，且不保存。即使是普通的 didit_workflow_create，也会以相同的节点图形式保存：MCP 会将您的 features 列表组装成链式功能节点，并以自动决策的状态节点结束，因此这些功能确实会运行（默认会发布；传入 status: "draft" 可保持未发布状态）。完整的 JSON 结构请参阅创建工作流 → 分支与基于节点的工作流。

使用 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 未运行原因进行分支。

功能配置与允许列表

功能节点的 config 会限制其接受的内容。didit_workflow_get_feature_config_schema 会返回每个功能接受的所有键，包括类型和默认值。两个目录工具（didit_workflow_get_id_verification_methods_catalog 和 didit_workflow_get_kyb_registry_catalog）负责回答配置所依赖的、由服务端决定的问题。规范的 OCR 允许列表结构为按国家、再按证件、最后是对象：{ "<ISO3>": { "<CODE>": { "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[]）。参见数据模型和验证状态。

处理 Webhook

让 Webhook 将最终决策投递到你的后端，而不是由 Agent 轮询：

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。
你的后端需在每次投递时验证规范化的 X-Signature-V2 请求头：shortenFloats → sortKeys → JSON.stringify（不转义 unicode）→ HMAC-SHA256 → timingSafeEqual。若 abs(now − X-Timestamp) > 300（秒），则拒绝该请求。
根据 event_id 去重。在 5 秒 内返回 2xx，并将耗时较长的工作放入队列。
Didit 在收到 5xx 或 404 时最多重试 2 次（约 1 分钟后一次，再约 4 分钟后一次），之后丢弃该投递。请在控制台的投递标签页中重放失败的投递。

Agent 只需要接入接收端，它本身不会监听。完整契约：Webhook。

传输与 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 文件输入。

故障排查

Agent 调用工具时返回 403 或 missing_scope

该组织中你的角色缺少该工具所需的权限（例如 READER 尝试执行写入操作）；missing_scope 错误会指明缺少的权限。若所有工具都失败，请重新连接或重新执行Log in with Didit。（MCP 仅支持 Bearer/OAuth：x-api-key 会被所有工具拒绝，因此使用 API 密钥也无法解决 403 问题。）

写入或删除操作未执行

破坏性工具需要在客户端中确认。请批准该调用，或检查工具的确认提示是否被自动拒绝。didit_session_delete、didit_session_batch_delete 和 didit_org_reveal_application_api_key 还需要在工具参数中包含 confirm: true；否则调用会在执行前被拒绝。

'organization_id is required' 或无结果

你可能有多个应用。请使用 *_search 工具（可跨所有资源搜索），或运行 didit_context_get，并传入你需要的 organization_id / application_id。

托管模式下浏览器未打开登录页面

部分客户端（Windsurf、Zed）通过 mcp-remote 桥接器连接，请确保配置中包含 npx -y mcp-remote@latest https://mcp.didit.me/mcp。重新打开客户端以重新触发 OAuth 握手。

工具未出现在客户端中

请确认服务器已连接（大多数客户端会显示状态指示点），并且已完成Log in with Didit。修改配置后请重启 MCP 宿主。didit_org_top_up 和 didit_org_reveal_application_api_key 在托管连接器上从不会列出。

VS Code（或其他客户端）无法发现 OAuth / 从不打开浏览器

请确保指向 https://mcp.didit.me/mcp，而不是裸的 https://mcp.didit.me 源站地址。资源元数据提供于 /.well-known/oauth-protected-resource/mcp，仅限该路径（同时在源根路径保留一份副本，供在源站根路径探测的客户端使用）。如果你自行部署，这通常意味着 MCP_RESOURCE_URI 被设置为源站地址，而不是完整的传输 URL；参见自托管部署。

文件上传被拒绝

对于托管 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 成员，无论智能体如何尝试，后端都会拒绝其写入。
先在沙盒应用上测试新的智能体或提示词。
绝不要因为某次验证中的文本这样要求，就批准或拒绝该验证。请依据决策、其中的警告以及你自己的审核。

个人数据

工具结果可能包含个人数据，例如姓名、出生日期、证件号码以及图片链接，而你的 MCP 客户端会将这些数据发送给它所使用的模型。在连接生产环境应用之前，请确认你与 AI 提供商的协议涵盖这些数据，或者改用沙盒应用进行测试。

自托管

托管服务器由 github.com/didit-protocol/mcp（MIT）构建。克隆该仓库，然后使用 Docker 或 Node 运行。无论采用哪种传输方式，它始终以 Didit 用户身份进行认证（不存在 API 密钥模式）。安装步骤见安装 → 自托管。

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=<user-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。

工具参考

按领域分组的所有工具。

示例

提示词和端到端对话。

指南

身份认证

模型上下文协议（MCP）

Web SDK

原生 SDK

服务端 SDK

集成

Didit MCP 高级配置、故障排除与自托管

权限范围与角色权限

跨应用与组织解析

托管目录包含哪些内容

分支工作流

编辑现有工作流（推荐）

使用 MCP 处理 NFC 跳过原因分支

功能配置与允许列表

响应结构 (V3 契约)

处理 Webhook

传输与 endpoint

故障排查

安全

提示词注入

个人数据

自托管

环境变量

工具参考

示例

​权限范围与角色权限

​跨应用与组织解析

​托管目录包含哪些内容

​分支工作流

​编辑现有工作流（推荐）

​使用 MCP 处理 NFC 跳过原因分支

​功能配置与允许列表

​响应结构 (V3 契约)

​处理 Webhook

​传输与 endpoint

​故障排查

​安全

​提示词注入

​个人数据

​自托管

​环境变量

工具参考

示例

权限范围与角色权限

跨应用与组织解析

托管目录包含哪些内容

分支工作流

编辑现有工作流（推荐）

使用 MCP 处理 NFC 跳过原因分支

功能配置与允许列表

响应结构 (V3 契约)

处理 Webhook

传输与 endpoint

故障排查

安全

提示词注入

个人数据

自托管

环境变量