> For the complete documentation index, see [llms.txt](https://doc.duaer.com/zh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.duaer.com/zh/advanced-ai/mcp/connect-ai-tools.md).

# 把常用 AI 工具连到 Duaer

在 Claude、Claude Code、ChatGPT、Cursor、VS Code 和 Codex 里接入 Duaer 的 MCP 服务端：地址、登录方式、每个工具的步骤、权限和常见问题。
## 开始之前

- 组织所有者或管理员在 Duaer 的设置 ›「MCP」里点「启用 MCP 访问」，见 [打开 Duaer MCP 服务端](/zh/advanced-ai/mcp/accessing-duaer-mcp-server.md)。
- 连接地址：Duaer 云上是 https://www.duaer.com/mcp-server/http；自托管是你的 Duaer 地址加 /mcp-server/http。
- Claude 和 ChatGPT 从它们自己的云端连接，不是从你的电脑。自托管的 Duaer 必须能从公网用 HTTPS 访问；放在内网或 VPN 后面的，要按它们的文档放行对方的 IP。

## 两种登录方式

- OAuth（推荐）：AI 工具第一次连接时会自动在 Duaer 注册自己，不用手动填客户端 ID 或密钥。随后会打开 Duaer 的授权页，你用自己的账号登录，勾选要给它的权限。之后令牌会自动续期。
- 访问令牌：在「MCP」的「连接详情」里生成访问令牌，作为 Authorization: Bearer <访问令牌> 请求头填进工具的配置。令牌只显示一次，相当于你本人的全部权限，不能按项勾选，请妥善保管。
- 无论哪种方式，AI 工具都不会拥有比你更多的权限：你看不到的资料、改不了的工作流程，它也碰不到。

## Claude（网页版和桌面版）

1. 打开 Customize › Connectors，点「+ Add」，选「Add custom connector」。
2. 名称填 Duaer，服务器地址填 https://www.duaer.com/mcp-server/http，点 Continue。
3. Authentication 选「Sign in when needed」或「Sign in now」；OAuth client 选「Register automatically」。
4. 点 Add，再点 Connect，在 Duaer 授权页勾选权限。
5. 在对话里点左下角的「+」›「Connectors」打开 Duaer。

Team 和 Enterprise 由所有者在 Organization settings › Connectors › Add › Custom › Web 添加，成员再到 Customize › Connectors 里各自点 Connect。免费版只能加一个自定义连接器。

更详细的 Claude 示例见 [用 MCP 把 Claude 连到 Duaer](/zh/advanced-ai/recipes/connect-claude-mcp.md)。

## Claude Code

在终端运行（加 --scope user 则对你的所有项目生效）：

```
claude mcp add --transport http duaer https://www.duaer.com/mcp-server/http --scope user
```

然后在 Claude Code 里输入 /mcp，或在终端运行 claude mcp login duaer，在浏览器里完成登录和授权。

用访问令牌：在命令后加 --header "Authorization: Bearer <访问令牌>"。

## ChatGPT

1. 在 ChatGPT 网页版打开 Plugins，点加号，选「Add custom MCP server」。
2. 填名称，在 Connection 下的 Server URL 填 https://www.duaer.com/mcp-server/http。
3. Authentication 选 OAuth。
4. 阅读风险提示，点「I understand and want to continue」，再点「Create as a plugin」。
5. 安装这个插件，在对话框里输入 @ 选择 Duaer，第一次使用时完成 Duaer 授权。

只能在网页版添加。能不能添加和使用自定义 MCP 服务器，由 ChatGPT 工作区的权限设置决定；如果看不到入口，请联系工作区管理员。

## Cursor

在 ~/.cursor/mcp.json（所有项目）或项目里的 .cursor/mcp.json 加入：

```
{
  "mcpServers": {
    "duaer": {
      "url": "https://www.duaer.com/mcp-server/http"
    }
  }
}
```

保存后 Cursor 会提示登录，按提示在浏览器里完成 Duaer 授权。出了问题，在 Output 面板选「MCP Logs」查看。

用访问令牌：在 duaer 下加 "headers": { "Authorization": "Bearer ${env:DUAER_MCP_TOKEN}" }，并设置环境变量 DUAER_MCP_TOKEN。

## VS Code 和 GitHub Copilot

1. 打开命令面板，运行「MCP: Add Server」。
2. 选「HTTP (HTTP or Server-Sent Events)」，填入地址，ID 填 duaer。
3. 给自己用就选 Global › Copilot Global，配置写进 ~/.copilot/mcp-config.json。
4. 第一次使用时按提示登录 Duaer；在 Chat: Open Customizations › Tools 里可以开关 Duaer 的工具。

```
{
  "mcpServers": {
    "duaer": {
      "type": "http",
      "url": "https://www.duaer.com/mcp-server/http"
    }
  }
}
```

如果你的 VS Code 没有出现登录提示，改用访问令牌：在 duaer 下加 "headers": { "Authorization": "Bearer ${DUAER_MCP_TOKEN}" }，并设置环境变量 DUAER_MCP_TOKEN。

## OpenAI Codex（命令行、IDE 插件和桌面应用）

三者共用 ~/.codex/config.toml。在终端运行：

```
codex mcp add duaer --url https://www.duaer.com/mcp-server/http
codex mcp login duaer
```

codex mcp login 会打开浏览器完成 Duaer 授权。用访问令牌：在 config.toml 的 [mcp_servers.duaer] 下加 bearer_token_env_var = "DUAER_MCP_TOKEN"，并设置这个环境变量。

## 授权页上的权限

- 工作流程：查找、查看、创建、修改、发布和运行工作流程。执行记录：查看运行结果。
- 知识库：`search_knowledge` 搜索资料，可以用 `fields` 只看带某些字段值的内容（例如 Jira 的状态）；`answer_knowledge` 带出处回答问题。
- 流程：读取流程概览、流程发现、单个事项和指标。
- 员工助手（`assistant:use`）：`list_assistants` 列出你能用的员工助手，`ask_assistant` 用某个助手的说明和知识来源回答问题，读的是你自己能看的资料，每次调用都记进这个助手的运行记录。默认不勾选，需要时手动勾上。见 [员工助手](/zh/portal/assistants.md)。
- 你的 Duaer 卡片（`card:decide`）和员工端操作（`action:run`）：列出并处理你的卡片（也可以今天先不动、收回，或者加上文件）、列出并运行员工端操作；处理卡片和运行操作都要你在 AI 工具里确认后才执行。默认不勾选。见 [卡片和员工端操作](/zh/advanced-ai/mcp/accessing-duaer-mcp-server.md#card-action-tools)。
- 另外还有智能体、技能、凭证、数据表、项目和文件夹、AI 偏好设置，以及在此实例安装社区节点。

只勾选要用的。授权过的工具会出现在「MCP」的 OAuth 客户端列表里，随时可以撤销；之后再连接时，上次勾选的会保持勾选。

## 给需要 Client ID 的 AI 平台注册客户端 <a href="#registered-clients" id="registered-clients"></a>

Claude、ChatGPT、Cursor 这类 AI 工具会自己注册，不用这一步。有些 AI 平台要你填 Client ID 和 Client Secret，这时由组织所有者或管理员先在 Duaer 里注册一个客户端：

1. 在 Duaer 打开「设置 › MCP」，在「已注册的客户端」里点「注册」。
2. 填名称，以及 AI 平台给出的回调 URL（每行一个，要用 HTTPS）。
3. 复制 Client ID、Client Secret、授权 URL 和 Token URL，填进 AI 平台。Client Secret 只显示这一次。

只有本组织的成员能通过这个客户端登录，别的组织的人会被拒绝。AI 平台可以用 Basic 头，也可以用表单字段传 Client Secret。Secret 泄露了就点「重新生成 Secret」，旧的立即失效；删除客户端后，通过它登录的人都会退出。

## 常见问题排查

- 提示「MCP access is disabled」：这个组织关闭了 MCP 访问，请所有者或管理员在「MCP」里打开。
- 工具列表里没有某个工具：授权时没有勾选对应权限（员工助手默认不勾选），断开后重新连接并勾选；知识库和员工助手的工具还需要 Duaer 开通知识库功能。
- 授权页提示回调地址不被允许：平台所有者设置了「允许的回调 URL」，需要把这个工具的回调地址加进去。Cursor 的是 https://www.cursor.com/agents/mcp/oauth/callback 和 http://localhost:8787/callback，其他工具见各自的文档。
- Claude 或 ChatGPT 连不上自托管的 Duaer：确认 Duaer 能从公网用 HTTPS 访问。
- `ask_assistant` 提示没有可用的助手：这个助手已停用、已删除，或者没有分享给你。
- `decide_card` 或 `run_action` 只给出员工端链接：这个 AI 工具不能弹出确认，或者卡片要选同事。到员工端处理。
- `answer_knowledge` 和 `ask_assistant` 每次调用都计入回答次数上限，并扣组织的积分；组织或你本人用到积分上限后会被拒绝。
## Questions

### 用 OAuth 还是访问令牌？

优先用 OAuth：可以按项勾选权限，令牌自动续期，也能在 Duaer 里随时撤销。访问令牌适合不支持 OAuth 的工具，它带着你本人的全部权限。

### AI 工具能看到同事分享给我的员工助手吗？

能，只要授权时勾选了「员工助手」。它列出的就是你在员工端能用的助手，回答时也只读你自己能看的资料。

### 要在 Duaer 里手动注册客户端吗？

不用。这些工具第一次连接时会自动注册；只有平台所有者限制了回调地址时，才需要把工具的回调地址加进允许列表。

## 相关

- [打开 Duaer MCP 服务端](https://doc.duaer.com/zh/advanced-ai/mcp/accessing-duaer-mcp-server.md)
- [用 MCP 把 Claude 连到 Duaer](https://doc.duaer.com/zh/advanced-ai/recipes/connect-claude-mcp.md)
- [员工助手：在 Duaer 员工端建自己的助手](https://doc.duaer.com/zh/portal/assistants.md)

