Dokki Docs logo

AI 用戶端

Master
On this page

當您想要 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 帳戶。

  • 決定用戶端需要的是個人、整個組織、選定的工作區，還是恰好一個工作區。

  • 從唯讀存取和非敏感性的測試資源開始。

  • 切勿將 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. 在同意畫面中，選擇 個人、一個或多個 組織 以及特定 工作區 的任何組合。

  5. 檢視選取的範圍並核准。

  6. 返回用戶端並執行唯讀測試。

選取個人會涵蓋符合資格的個人工作區。選取組織會涵蓋該組織命名空間，包括稍後新增的符合資格工作區，而特定工作區的選取則僅限於那些工作區。組織成員資格、工作區成員資格、資源共用、私人資源規則和封存工作區排除仍然適用。OAuth 絕不會將檢視者變成編輯者，也不會揭露私人資源。

若要稍後新增或移除範圍，請重新連線或重新授權，並進行新的同意選擇。不要假設傳入不同的 workspace_id 可以擴充現有的授權。

API 金鑰 — 用於受信任的非互動式用戶端

Dokki API 金鑰以 dk_ 開頭。請從用戶端設定對話方塊或帳戶設定中產生。

  • 金鑰限於目前的個人內容或一個組織。

  • 它不限於單一工作區；如果需要該界限，請使用工作區連接器。

  • 建立時會顯示原始金鑰。請將其存放在用戶端的認證儲存或祕密管理器中。

  • 以 Authorization: Bearer YOUR_API_KEY 傳送。

  • 當用戶端、擁有者或機器變更時，請撤銷金鑰。

API 金鑰仍使用執行中使用者的 Dokki 權限。有效的金鑰不會繞過組織成員資格、工作區角色、私人資源、封存的工作區或特定動作的權限檢查。

工作區連接器 — 用於一個固定的工作區

工作區連接器由工作區管理員建立，並鎖定到恰好一個工作區。請將其用於 CI 作業、共用自動化、專用代理程式或不得存取其他工作區的機器。

連接器提供包含工作區 ID、連接器 ID 和一次性權杖的獨立 URL。建立時請複製並安全存放。請參閱 工作區連接器 以了解 Documents、Publish 和 Memory 連接器的類型、用戶端程式碼片段、輪換和撤銷。

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_...

  • 固定工作區驗證：使用完整的 Workspace Connector URL

  • 傳輸：無狀態 Streamable HTTP

用戶端在使用 Workspace Connector 時，必須保留確切的 connector URL 和查詢參數。

AI 用戶端能力

新的 AI 用戶端連線應使用 https://dokki.one/mcp/v2。它使用 Streamable HTTP，並公開八個可探索的 facade 工具，以及 preview_resource。憑證範圍和目前的 Dokki 權限決定哪些操作實際成功。

find

列出授權的工作區、瀏覽資源、依意義搜尋、grep 確切文字或識別碼、發現相關知識，以及列出 Artifact 範本。

read

讀取文件、表格、Artifact 和檔案。文件支援檢視、大綱和編輯定位模式；表格支援篩選、排序、投影、分頁和彙總。

create

建立資料夾、文件、表格、Artifact 和檔案。租戶範圍的憑證也可以在所選的個人或組織範圍允許時建立工作區。

edit

重新命名、移動、加上標籤、移除標籤或封存資源；編輯文件節點；變更表格列、欄和儲存格；以及更新 Artifact 來源。破壞性操作和支援的並行寫入會新增確認或比較並設定的界限。

share

與使用者共用資源，或在操作身分可以管理共用時變更公開存取。公開共用變更需要確認。

message

列出工作區 Channel 成員，並傳送或讀取 Channel 訊息。可用的審閱操作仍受工作區成員資格和目前的 message facade 所約束。

publish

管理已授權工作區的公開網站、已發佈的資源、精選內容和自訂網域。發佈資源需要確認。

connect

透過操作使用者的已連線帳戶，列出、授權、檢查、中斷連線和呼叫支援的外部整合。這是產品 MCP Apps 方向的 MCP 表示。

preview_resource

在支援 MCP Apps UI 資源的 MCP 主機中，為文件、表格或 Artifact 開啟轉譯的內嵌預覽。當結構化資料足夠時，使用一般的讀取操作。

AI 用戶端授權的評估方式

  1. 驗證 OAuth 授權、dk_ API 金鑰或 Workspace MCP Connector。

  2. 解析個人、組織、選定工作區或固定工作區範圍。

  3. 確認操作身分仍屬於租戶，且可以存取工作區。

  4. 套用私人資源和資源角色檢查。

  5. 套用 facade 動作的讀取、寫入、共用、發佈、訊息或外部應用程式需求。

  6. 對受保護的重大操作要求確認。

用戶端可能發現某個工具，但特定呼叫仍被拒絕。工具探索並不能證明每個工作區、資源或操作都已獲得授權。

端點相容性

  • 建議：https://dokki.one/mcp/v2 — 基於 facade 的 AI 用戶端介面。

  • 相容的舊版端點：https://dokki.one/api/mcp — 許多個別工具；僅保留給尚未遷移的現有組態。

  • 舊版組織 URL，例如 /api/mcp/org/<orgId>，仍然是相容路徑。新的 OAuth 連線在同意期間會選取個人、組織和工作區範圍。

  • Workspace MCP Connector 會重複使用適當的端點，在產生的 URL 中帶有固定工作區、connector id 和 connector token。務必複製完整的產生 URL。

端對端驗證連線

依序執行這些檢查：

  1. 工具探索 — 確認預期的 facade 工具可見。

  2. 身分和範圍 — 使用 action: "workspaces" 呼叫 find，並檢查只有預期的工作區出現。

  3. 讀取 — 列出一個允許的工作區中的資源，然後讀取已知的文件。

  4. 寫入界限 — 僅在必要時，建立或編輯一次性的測試資源並讀取回來。

  5. 拒絕界限 — 確認未選取的工作區或未授權的資源不會暴露。

  6. 清理 — 移除測試資源並確認其不存在。

成功的連線並不證明每個操作都允許。每個動作都會再次根據憑證範圍、目前成員資格、資源權限和動作特定需求進行檢查。

疑難排解

  • 沒有開啟瀏覽器 — 從用戶端的 MCP 設定重新開始授權；確認用戶端支援遠端 OAuth。

  • 401 Unauthorized — 權杖或金鑰遺失、過期、撤銷、格式錯誤，或附加到錯誤的端點。請重新授權或更換憑證。

  • 403 Forbidden — 驗證成功，但選取的範圍或目前的 Dokki 角色不允許此操作。

  • 工作區遺失 — 重新授權 OAuth 並選取個人、組織或特定工作區；同時確認它未被封存，且您的帳戶可以存取它。

  • 出現錯誤的工作區 — 撤銷連線並以預期的選擇建立授權。

  • 工具遺失 — 確認用戶端使用 /mcp/v2，重新整理工具探索，然後重新啟動用戶端。Workspace Documents Connector 會故意省略 publish 和 connect。

  • 出現舊的平面工具名稱 — 用戶端正在使用 /api/mcp；在相容時將其遷移至 /mcp/v2。

  • 讀取成功後寫入遭拒 — 憑證可以存取資源，但操作身分缺少編輯或管理權限。

  • Connector 範圍不符 — 使用完整的產生 connector URL。不同的 workspace id 或 connector id 會被拒絕。

  • 連線正常但外部應用程式無法運作 — MCP 用戶端對 Dokki 的存取和 Dokki 的對外 MCP Apps 是分開的。檢查 Connect → MCP Apps 和操作使用者的應用程式連線。

檢視目前有存取權的人員

開啟 Connect → AI Clients 並檢閱 Authorized clients，再將近期活動作為存取檢查。此帳戶層級清單包含個人、組織及個別工作空間的授權，並將每個授權標示為有效、已過期或已撤銷。

如果清單無法載入，Dokki 會顯示錯誤，而非空白狀態。近期活動回答的是另一個問題：安靜的用戶端仍可能持有有效的授權，而舊的活動記錄可能屬於已過期或已撤銷的授權。

撤銷存取

  • OAuth：從 Dokki 或用戶端移除或重新連線 AI 用戶端。

  • API 金鑰：在帳戶設定中撤銷 dk_ 金鑰。

  • 工作空間連接器：在 Workspace → Extensions → Connectors 中撤銷。

  • MCP 應用程式：在 Connect → MCP Apps 下中斷外部帳戶的連線。

撤銷會停止未來的工具呼叫，但不會刪除已建立的文件、匯入、訊息或外部服務變更。