> ## 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 登录（OAuth）

> Didit MCP 如何进行认证：OAuth 2.1 与 PKCE、动态客户端注册、资源元数据、权限范围、角色，以及各客户端的连接方式。

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 客户端会自动执行标准流程：

**1. 发现**

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

```text theme={null}
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` 提供，供会先探测该路径的客户端使用。

**2. 注册（动态客户端注册）**

客户端读取 `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`；此类客户端需要由运营人员先行注册。

**3. 授权（PKCE）**

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

**4. 同意**

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

**5. 调用工具**

客户端在每次请求中都会携带 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`。

[工具参考](https://docs.didit.me/zh/integration/mcp/tools.md)列出了每个工具所属的作用域。您批准的作用域会附加在 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`）；[工具参考](https://docs.didit.me/zh/integration/mcp/tools.md)逐个列出了每个工具对应的权限。服务器在发送请求前也会检查该权限，所用的权限信息来自内省响应中针对您所在组织的权限信息：

* 在 `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 登录**。

退出控制台不会让已连接的应用退出登录，断开某个应用也不会让你在任何地方退出登录。

### 断开应用

**1. 通过控制台**

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

**2. 通过应用（RFC 7009）**

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

```bash theme={null}
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>"}'
```

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

***

## 在每个客户端中连接

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

> [tab] Claude
>
> 使用 Business Console 集成页面上显示的深层链接。它会打开 claude.ai，并预先填好 **Add custom connector** 对话框：
>
> ```text theme={null}
> 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](https://docs.didit.me/zh/integration/mcp/claude.md)。

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http didit https://mcp.didit.me/mcp
> ```
>
> 然后在 Claude Code 中运行 `/mcp`，启动浏览器登录。

> [tab] Cursor
>
> `~/.cursor/mcp.json`：
>
> ```json theme={null}
> { "mcpServers": { "didit": { "url": "https://mcp.didit.me/mcp" } } }
> ```
>
> Cursor 会自行注册，并在首次使用时打开浏览器。

> [tab] 通用客户端
>
> 将任何支持 OAuth 2.1 的 Streamable HTTP 客户端指向 `https://mcp.didit.me/mcp`。它应当：
>
> 1. 向 `POST /mcp` 发送请求，收到 `401`，并从 `WWW-Authenticate` 中读取 `resource_metadata`。
> 2. 获取 `https://mcp.didit.me/.well-known/oauth-protected-resource/mcp`，然后获取 `https://business.didit.me/.well-known/oauth-authorization-server` 的授权服务器元数据。
> 3. 如果没有客户端 ID，则在 `registration_endpoint` 进行注册。
> 4. 在 `authorization_endpoint` 执行带 PKCE（S256）的授权码流程，并在 `token_endpoint` 交换授权码。
> 5. 在每次 `POST /mcp` 请求中发送 `Authorization: Bearer <access_token>`。
>
> 不支持 OAuth 的客户端可以通过 `npx -y mcp-remote@latest https://mcp.didit.me/mcp` 代为完成步骤 1–5。

***

## 身份验证失败

```text theme={null}
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**：在该页面断开连接的应用必须重新批准。

***

> [card] [工具参考](https://docs.didit.me/zh/integration/mcp/tools.md)
>
> 各工具的功能、所需权限范围及角色权限。

> [card] [高级](https://docs.didit.me/zh/integration/mcp/advanced.md)
>
> 角色、跨应用行为和自托管。


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