AI 客户端

当您希望 Dokki 外部的 AI 工具搜索、读取、创建或更新 Dokki 资源时，请使用外部 MCP 客户端。Dokki 支持 Streamable HTTP MCP 客户端，包括 Claude、Claude Desktop、Claude Code、Codex CLI、Codex App、Cursor 以及兼容的自定义客户端。

推荐端点

对于每个新连接，请使用规范的 facade 端点：

https://dokki.one/mcp/v2

它公开了八个高级工具——find、read、create、edit、share、message、publish 和 connect——以及 preview_resource。每个 facade 接受一个 action、顶级资源或工作区 ID 以及一个 args 对象。这个紧凑的表面更易于代理发现，并在凭据允许时包含发布和连接应用访问。

旧的扁平端点 https://dokki.one/api/mcp 仍可用于较旧的客户端配置。它公开了许多单独的工具，而不是 facade 表面。除非现有集成明确依赖旧工具名称，否则请使用 /mcp/v2。

连接之前

• 登录拥有或可以访问所需工作区的 Dokki 账户。

• 确定客户端需要 Personal、整个组织、选定的工作区还是恰好一个工作区。

• 从只读访问和非敏感测试资源开始。

• 切勿将 API 密钥或连接器令牌粘贴到 Dokki 文档、聊天、截图或源代码存储库中。

打开 工作区 → 扩展 → 连接 → AI 客户端，然后选择 设置客户端。对话框显示 Claude、Codex、Claude Code 和 Cursor 的当前说明，并允许您选择 OAuth 或 API 密钥。

选择授权方法

OAuth — 推荐给使用交互式客户端的个人

当客户端可以打开浏览器进行登录时，请选择 OAuth。

1. 将 https://dokki.one/mcp/v2 添加到客户端。

2. 启动连接。客户端发现 Dokki 的 OAuth 配置并在浏览器中打开 Dokki。

3. 登录 Dokki。

4. 在同意屏幕上，选择 Personal、一个或多个 组织 以及特定 工作区 的任意组合。

5. 查看所选范围并批准。

6. 返回客户端并运行只读测试。

选择 Personal 涵盖符合条件的 Personal 工作区。选择组织涵盖该组织命名空间，包括以后添加的符合条件的工作区，而特定工作区选择仍仅限于这些工作区。组织成员资格、工作区成员资格、资源共享、私有资源规则和已归档工作区排除仍然适用。OAuth 永远不会将查看者变成编辑者或泄露私有资源。

要稍后添加或删除范围，请重新连接或重新授权并进行新的同意选择。不要假设传递不同的 workspace_id 可以扩展现有授权。

API 密钥 — 用于受信任的非交互式客户端

Dokki API 密钥以 dk_ 开头。从客户端设置对话框或账户设置中生成它。

• 密钥的范围限定为当前 Personal 上下文或一个组织。

• 它不限于一个工作区；当需要该边界时，请使用工作区连接器。

• 创建时会显示原始密钥。将其存储在客户端的凭据存储或机密管理器中。

• 将其作为 Authorization: Bearer YOUR_API_KEY 发送。

• 当客户端、所有者或机器更改时，撤销该密钥。

API 密钥仍使用操作用户的 Dokki 权限。有效密钥不会绕过组织成员资格、工作区角色、私有资源、已归档工作区或特定于操作的权限检查。

工作区连接器 — 用于一个固定的工作区

工作区连接器由工作区管理员创建，并锁定到恰好一个工作区。将其用于 CI 作业、共享自动化、专用代理或不得访问其他工作区的机器。

连接器提供包含工作区 ID、连接器 ID 和一次性令牌的自包含 URL。创建时复制它并安全存储。有关文档、发布和内存连接器类型、客户端片段、轮换和撤销，请参阅 工作区连接器。

Claude 和 Claude Desktop

对于使用自定义连接器的 Claude 或 Claude Desktop：

1. 打开 设置 → 连接器 → 添加自定义连接器。

2. 输入 https://dokki.one/mcp/v2。

3. 在浏览器中完成 Dokki OAuth。

4. 返回 Claude 并确认 Dokki 工具出现。

5. 请求只读操作，例如列出可访问的工作区。

如果客户端请求手动 bearer 凭据而不是 OAuth，请使用适合所需范围的 dk_ API 密钥或工作区连接器 URL。

Claude Code

对于直接 OAuth 连接，请运行：

claude mcp add dokki --transport http https://dokki.one/mcp/v2

然后启动 Claude Code，完成浏览器授权，并确认 Dokki 服务器已连接。Dokki Claude Code 插件也可能将同一端点与 Dokki 技能和命令捆绑在一起；当您同时需要 MCP 服务器和任务指导时，请使用该插件。

对于 API 密钥身份验证，请使用 Dokki 设置对话框中显示的标头添加同一端点。将密钥保留在 shell 历史和项目文件之外。

Codex CLI 和 Codex App

Dokki 插件是 Codex App 的首选路径：安装 Dokki，完成 OAuth，并选择它可以访问的工作区或组织。该插件使用 /mcp/v2 facade 并提供 Dokki 特定的技能。

对于手动 Codex CLI 连接，请将其添加到 ~/.codex/config.toml：

[mcp_servers.dokki]
command = "npx"
args = ["-y", "mcp-remote", "https://dokki.one/mcp/v2"]

重启 Codex，完成 OAuth，并验证服务器公开了 find、read、create、edit、share、message、publish、connect 和 preview_resource。

对于 API 密钥身份验证，请使用 Dokki 设置对话框中生成的配置，以便桥接器传递 Authorization 标头。不要将密钥提交到存储库级配置中。

Cursor

将其添加到 ~/.cursor/mcp.json：

{"mcpServers":{"dokki":{"url":"https://dokki.one/mcp/v2"}}}

重启 Cursor 并完成 OAuth。如果 Cursor 需要手动凭据，请使用 Dokki 生成的 API 密钥版本，并在服务器标头中使用 Authorization: Bearer YOUR_API_KEY。

其他 MCP 客户端

对于任何兼容 Streamable HTTP 的客户端：

• 服务器 URL：https://dokki.one/mcp/v2

• 首选认证：OAuth 发现

• 备选认证：Authorization: Bearer dk_...

• 固定工作区认证：使用完整的工作区连接器 URL

• 传输：无状态流式 HTTP

使用工作区连接器时，客户端必须保留确切的连接器 URL 和查询参数。

AI 客户端功能

新的 AI 客户端连接应使用 https://dokki.one/mcp/v2。它使用流式 HTTP，并公开八个可发现的门面工具以及 preview_resource。凭据范围和当前的 Dokki 权限决定哪些操作实际成功。

find

列出授权的工作区，浏览资源，按含义搜索，精确搜索文本或标识符，发现相关知识，并列出 Artifact 模板。

read

读取文档、表格、Artifact 和文件。文档支持视图、大纲和编辑定位模式；表格支持筛选、排序、投影、分页和聚合。

create

创建文件夹、文档、表格、Artifact 和文件。当所选的个人或组织范围允许时，租户范围的凭据也可以创建工作区。

edit

重命名、移动、标记、取消标记或归档资源；编辑文档节点；更改表格行、列和单元格；以及更新 Artifact 源。破坏性操作和支持的并发写入会添加确认或比较并设置边界。

share

当操作身份可以管理共享时，与用户共享资源或更改公共访问权限。公共共享更改需要确认。

message

列出工作区频道成员并发送或读取频道消息。可用的审查操作仍受工作区成员资格和当前消息门面的约束。

publish

管理授权工作区的公共站点、已发布资源、精选内容和自定义域。发布资源需要确认。

connect

通过操作用户的已连接账户列出、授权、检查、断开和调用支持的外部集成。这是产品 MCP 应用方向的 MCP 表示。

preview_resource

在支持 MCP 应用 UI 资源的 MCP 主机中，为文档、表格或 Artifact 打开渲染的内联预览。当结构化数据足够时，使用常规读取操作。

AI 客户端授权如何评估

1. 验证 OAuth 授权、dk_ API 密钥或工作区 MCP 连接器。

2. 解析个人、组织、选定工作区或固定工作区范围。

3. 确认操作身份仍属于租户并且可以访问工作区。

4. 应用私有资源和资源角色检查。

5. 应用门面操作的读取、写入、共享、发布、消息或外部应用要求。

6. 对受保护的重要操作要求确认。

客户端可能会发现某个工具，但特定调用仍被拒绝。工具发现并不证明每个工作区、资源或操作都已授权。

端点兼容性

• 推荐：https://dokki.one/mcp/v2 — 基于门面的 AI 客户端界面。

• 兼容的旧端点：https://dokki.one/api/mcp — 许多单独的工具；仅保留给尚未迁移的现有配置。

• 旧的组织 URL（如 /api/mcp/org/<orgId>）仍然是兼容路径。新的 OAuth 连接在同意期间选择个人、组织和工作区范围。

• 工作区 MCP 连接器在生成的 URL 中重用适当的端点，并带有固定的工作区、连接器 ID 和连接器令牌。始终复制完整的生成 URL。

端到端验证连接

按顺序运行这些检查：

1. 工具发现 — 确认预期的门面工具可见。

2. 身份和范围 — 使用 action: "workspaces" 调用 find，并检查只出现预期的工作区。

3. 读取 — 列出一个允许的工作区中的资源，然后读取已知文档。

4. 写入边界 — 仅在需要时，创建或编辑一次性测试资源并读回。

5. 拒绝边界 — 确认未选择的工作区或未授权的资源不会暴露。

6. 清理 — 删除测试资源并确认其不存在。

成功的连接并不证明每个操作都被允许。每个操作都会根据凭据范围、当前成员资格、资源权限和特定操作要求再次检查。

故障排除

• 浏览器未打开 — 从客户端的 MCP 设置重新开始授权；确认客户端支持远程 OAuth。

• 401 未授权 — 令牌或密钥缺失、过期、被撤销、格式错误或附加到错误的端点。重新授权或替换凭据。

• 403 禁止 — 身份验证成功，但所选范围或当前的 Dokki 角色不允许该操作。

• 工作区缺失 — 重新授权 OAuth 并选择个人、组织或特定工作区；同时确认它未被归档并且您的账户可以访问它。

• 出现错误的工作区 — 撤销连接并使用预期的选择创建授权。

• 工具缺失 — 确认客户端使用 /mcp/v2，刷新工具发现，并重启客户端。工作区文档连接器有意省略 publish 和 connect。

• 出现旧的扁平工具名称 — 客户端正在使用 /api/mcp；在兼容时将其迁移到 /mcp/v2。

• 读取成功后写入被拒绝 — 凭据可以访问资源，但操作身份缺少编辑或管理权限。

• 连接器范围不匹配 — 使用完整的生成连接器 URL。不同的工作区 ID 或连接器 ID 将被拒绝。

• 连接正常但外部应用无法工作 — MCP 客户端对 Dokki 的访问和 Dokki 的出站 MCP 应用是分开的。检查 连接 → MCP 应用 和操作用户的应用连接。

查看当前谁有访问权限

打开 连接 → AI 客户端 并查看 已授权的客户端，然后再将近期活动用作访问检查。此账户级列表包含个人、组织和单个工作空间的授权，并将每个授权标记为有效、已过期或已撤销。

如果列表无法加载，Dokki 会显示错误而不是空状态。近期活动回答的是另一个问题：一个不活跃的客户端可能仍持有有效授权，而一条旧的活动记录可能属于已过期或已撤销的授权。

撤销访问权限

• OAuth：从 Dokki 或客户端移除或重新连接 AI 客户端。

• API 密钥：在账户设置中撤销 dk_ 密钥。

• 工作区连接器：在 工作区 → 扩展 → 连接器 中撤销它。

• MCP 应用：在 连接 → MCP 应用 下断开外部账户。

撤销会停止未来的工具调用。它不会删除已创建的文档、导入、消息或外部服务更改。