Didit MCP 认证：使用 Didit 登录（OAuth）

Didit MCP 通过 使用 Didit 登录（OAuth 2.1）进行身份认证。它以 Didit 用户的身份运行，并拥有您控制台角色的权限，没有 API 密钥模式。

使用 Didit 登录

托管服务器（https://mcp.didit.me/mcp）是 OAuth 2.1 资源服务器。Didit Business Console（business.didit.me）是授权服务器，负责托管授权同意页面并颁发 token。您的 MCP 客户端会自动执行标准流程：

发现

客户端在未携带 token 的情况下向 /mcp 发送请求，并收到 401 响应。响应头 WWW-Authenticate: Bearer 中的 resource_metadata 指向受保护资源元数据（RFC 9728）：

https://mcp.didit.me/.well-known/oauth-protected-resource/mcp

该文档列出了资源（https://mcp.didit.me/mcp）、授权服务器（https://business.didit.me）以及支持的作用域。同一文档也在源站根路径 https://mcp.didit.me/.well-known/oauth-protected-resource 提供，供会先探测该路径的客户端使用。

客户端读取 https://business.didit.me/.well-known/oauth-authorization-server 处的授权服务器元数据。如果还没有客户端 ID，则会向 registration_endpoint 注册自己（RFC 7591）。您无需预先在自己这边做任何配置：使用环回或原生回调的本地客户端（Claude Code、Cursor、MCP Inspector）以及使用经过审核回调的云托管客户端（Claude）都以这种方式注册。Didit 未审核的远程回调 URL 会被拒绝，并返回 invalid_redirect_uri；此类客户端需要由运营人员先行注册。

授权（PKCE）

客户端打开 https://business.didit.me/authorize，并附带 S256 PKCE 挑战。您登录（或注册）后，会看到所请求的确切权限。客户端为公共客户端：token 端点不接受客户端密钥（token_endpoint_auth_methods_supported 为 none），因此 PKCE 负责将授权码与客户端绑定。

同意

您批准授权。控制台会为该应用创建会话，并绑定到您批准的作用域，然后返回授权码。客户端再在 token_endpoint 用该授权码换取 access token 和 refresh token。

调用工具

客户端在每次请求中都会携带 access token。MCP 通过 RFC 7662 token 内省，向 Didit 身份服务验证 token（token 为 opaque token，而非 JWT），从内省响应中读取针对您所在组织的权限信息，并在该请求期间以您的身份执行操作。

作用域

资源元数据中列出了三个作用域。授权同意页面会用通俗的语言说明客户端所请求的作用域：

作用域	授予的权限
`didit:management`	管理您的工作区：`organization`、`members`、`subscription`、`users`、`applications`、`workflows`、`customization`、`questionnaires`、`lists`、`webhooks`、`integrations`、`api-keys`、`audit-logs`、`roles`、`saml` 和 `analytics`。
`didit:verification`	运行并审核验证：`sessions`、`businesses`、`cases`、`networks`、`transactions`、`blocklist` 和 `analytics`。
`didit:staff`	保留给 Didit 员工账户。对普通账户不解锁任何权限，开源版本也未定义任何仅限员工使用的工具。

两个作用域都包含 analytics。管理 lists 需要 didit:management；访问 blocklist 需要 didit:verification。工具参考列出了每个工具所属的作用域。您批准的作用域会附加在 token 上，并在服务器端强制执行。因此，即使您自己的角色有权访问管理功能，仅连接了 didit:verification 的应用仍会在管理功能上被拒绝。授权服务器也支持 OpenID 作用域（openid profile email）；仅请求这些作用域的连接只能识别您的身份，无法访问其他内容。应用的实际权限是已批准作用域与您的控制台角色的交集，绝不是二者中较宽的那个。要使用 didit_session_create 创建验证会话，您需要 didit:verification 作用域，并且需要具备 create:sessions 或 write:sessions 的角色。开发者角色包含 create:sessions。仅批准 didit:management 并不允许创建会话，即使您的角色具有所需权限也是如此。

角色与权限

token 代表的是您本人，因此智能体可以通过一个连接，跨您所属的每个组织开展工作。跨应用工具（didit_session_search、didit_analytics、didit_context_get 以及其他 *_search 工具）会自动汇总所有组织的数据。您的角色始终由 Didit 后端按组织强制执行。每个工具对应一个后端权限字符串（例如 didit_session_update_status 对应 write:sessions，didit_session_delete 对应 delete:sessions）；工具参考逐个列出了每个工具对应的权限。服务器在发送请求前也会检查该权限，所用的权限信息来自内省响应中针对您所在组织的权限信息：

在 enforce 模式下，角色无权运行的工具会从 tools/list 中剔除。若仍调用该工具，将返回 missing_scope 错误，并指明所需权限（"Your role in this organization does not include the permission 'delete:sessions' that didit_session_delete requires."）。
在 shadow 模式（服务器默认值）下，所有工具都会列出，调用会转发至后端。若角色缺少相应权限，后端将返回 403。该判定结果仅记录在服务器的审计日志中。

无论哪种模式，MCP 都绝不会授予超出您控制台角色已允许范围的权限。READER 可以列出和读取；OWNER 或 ADMIN 可以写入和删除。

token 有效期

已批准的应用会获得自己的会话，独立于您批准该应用时所用的浏览器会话。access token 的有效期较短。客户端会使用 refresh token 静默刷新（grant_types_supported 包含 refresh_token）。刷新会保留应用的作用域，并始终绑定到该应用。如果刷新失败（例如您断开了应用的连接），客户端会在下一次调用时重新执行使用 Didit 登录。退出控制台不会让已连接的应用退出登录，断开某个应用也不会让你在任何地方退出登录。

断开应用

通过控制台

Settings → Authentication → Connected apps 列出你批准过的每个应用，包括其注册名称和被授予的权限。点击断开会立即终止该应用的访问：其访问令牌和刷新令牌都将失效，其他内容不受影响。

通过应用（RFC 7009）

客户端可以向授权服务器的 revocation_endpoint 发送令牌，主动撤销自己的访问权限。该端点列在 https://business.didit.me/.well-known/oauth-authorization-server 的元数据中。按照 RFC 7009 的要求，撤销请求成功时，无论令牌当时是否仍然有效，都返回 200，因此响应不会告诉你令牌是否有效。503 表示撤销未能生效：应将该令牌视为仍然有效，并重试。

curl -X POST https://business.didit.me/api/auth/oauth-revoke \
  -H "Content-Type: application/json" \
  -d '{"token": "<refresh-or-access-token>", "token_type_hint": "refresh_token", "client_id": "<your-client-id>"}'

为什么不用 API 密钥？ 每个 MCP 工具都会调用以用户为作用域的控制台端点（/organization/{org}/application/{app}/…），这些端点使用按角色划分权限的 Bearer 令牌进行授权，并且拒绝 x-api-key。应用 API 密钥用于从你自己的后端直接调用 REST API（例如创建会话），而不用于本 MCP。didit_org_list_api_keys 显示密钥的元数据，其中的值已隐藏；用于显示原始密钥的工具在托管连接器上被隐藏。

在每个客户端中连接

每个客户端都执行相同的流程，区别只在于你提供 URL 的方式。

Claude
Claude Code
Cursor
通用客户端

使用 Business Console 集成页面上显示的深层链接。它会打开 claude.ai，并预先填好 Add custom connector 对话框：

https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Didit&connectorUrl=https://mcp.didit.me/mcp

确认后，完成 使用 Didit 登录。Claude Desktop 使用同一 URL，路径为 Settings → Connectors → Add custom connector。详情请见连接 Claude。

claude mcp add --transport http didit https://mcp.didit.me/mcp

然后在 Claude Code 中运行 /mcp，启动浏览器登录。

~/.cursor/mcp.json：

{ "mcpServers": { "didit": { "url": "https://mcp.didit.me/mcp" } } }

Cursor 会自行注册，并在首次使用时打开浏览器。

将任何支持 OAuth 2.1 的 Streamable HTTP 客户端指向 https://mcp.didit.me/mcp。它应当：

向 POST /mcp 发送请求，收到 401，并从 WWW-Authenticate 中读取 resource_metadata。
获取 https://mcp.didit.me/.well-known/oauth-protected-resource/mcp，然后获取 https://business.didit.me/.well-known/oauth-authorization-server 的授权服务器元数据。
如果没有客户端 ID，则在 registration_endpoint 进行注册。
在 authorization_endpoint 执行带 PKCE（S256）的授权码流程，并在 token_endpoint 交换授权码。
在每次 POST /mcp 请求中发送 Authorization: Bearer <access_token>。

不支持 OAuth 的客户端可以通过 npx -y mcp-remote@latest https://mcp.didit.me/mcp 代为完成步骤 1–5。

身份验证失败

HTTP 401
WWW-Authenticate: Bearer error="invalid_token", error_description="Missing Authorization header", resource_metadata="https://mcp.didit.me/.well-known/oauth-protected-resource/mcp"

来自 /mcp 的 401 表示令牌缺失、已过期或已被撤销，客户端应刷新令牌，或重新执行 使用 Didit 登录。针对特定工具的 403 或 missing_scope 错误，通常意味着以下两种情况之一：你的角色缺少该权限（例如 READER 尝试写入操作），或者连接在批准时未包含该工具所需的权限范围。这并不意味着整个连接已损坏。重新连接并批准两个权限范围可解决第二种情况；第一种情况则需要更改角色。如果所有工具都失败，请在控制台中检查 Settings → Authentication → Connected apps：在该页面断开连接的应用必须重新批准。

工具参考

各工具的功能、所需权限范围及角色权限。

高级

角色、跨应用行为和自托管。

指南

身份认证

模型上下文协议（MCP）

Web SDK

原生 SDK

服务端 SDK

集成

Didit MCP 认证：使用 Didit 登录（OAuth）

使用 Didit 登录

作用域

角色与权限

token 有效期

断开应用

在每个客户端中连接

身份验证失败

工具参考

高级

​使用 Didit 登录

​作用域

​角色与权限

​token 有效期

​断开应用

​在每个客户端中连接

​身份验证失败

工具参考

高级

使用 Didit 登录

作用域

角色与权限

token 有效期

断开应用

在每个客户端中连接

身份验证失败