讀時間： 約 8 分鐘 · 系列： 平台啟用（數據工程）進階 · 上一步： .lantide 匯出匯入 · 下一步： MCP Sources 入門
先分清楚兩個方向
團隊說「要用 MCP」時，可能在談兩件完全不同的事：
| 方向 | Lantide 的角色 | 你會在什麼地方設定 | 用途 |
|---|---|---|---|
| Agent Integration | MCP server | 右上角 Agent Integration | 讓 Cursor、Codex、Claude 等外部 Agent 讀取或操作 Lantide 工作環境 |
| MCP Sources | MCP client | 側邊欄 MCP Sources | 把外部 API 或資料服務物化成 Lantide 可查詢的表 |
本篇談第一種：讓外部 Agent 連入 Lantide。如果你要接資料源，請讀 MCP Sources 入門。兩者都叫 MCP，但連線方向、權限與故障排除方式不同。
Execute 模式 的外部 Agent 也可透過 Lantide 代為呼叫 MCP Sources（mcp_explore、mcp_pull_table、mcp_test_source、mcp_connect_source 等），與內建 Agent 共用同一組來源設定；Admin 才可新增／換憑證／Remove。Observe 僅能讀已物化表與 schema，不能對遠端 call_tool。
什麼時候值得開 Agent Integration
適合：
- 分析師已在 Cursor、Codex 或 Claude 中工作，希望沿用原本的對話介面。
- 團隊仍要求 Plan、SQL evidence、Report 與 Activity 留在 Lantide。
- 你需要一個可查看、可限制、可撤銷的本機 Agent 入口，而不是把資料與憑證交給遠端 API。
可以不開：
- 團隊只使用 Lantide 內建 Agent。
- 只是要讓 Lantide 讀取外部 API；那是 MCP Sources。
- 外部 Agent 跑在另一台機器或雲端服務。Agent Integration 綁定本機 loopback，不是遠端共享 API。
第一次連線（First-run）
首次啟動須先選 Setup Mode Choice：Built-in Agent (BYOK) 或 External Agent (MCP)（見 USER_GUIDE §2.1）。
External 路徑： 選 External 後 Lantide 會開啟 Agent Integration，建議建立 All workspaces 的 Persistent profile。一般 client 複製 connection kit（完整的 mcpServers 具名 entry，例如 lantide-<alias>）並合併進既有 MCP client 設定；不要整檔覆寫。從支援的 Codex 本機流程啟動時，可改用 GUI 的 Approve & Connect：先檢查 scope、mode、expiry、exposure 與設定檔目的地，再建立 credential 並合併設定；credential 不會顯示在聊天或 deep link。再 Copy onboarding prompt 貼到外部 Agent。該 prompt 已含 All-workspaces 的 精簡固定 tools/list → 選工作區 → get_analysis_context 指引；長尾能力透過 capability search/invoker 使用，選定後不需重新載入工具。Agent 依 playbook version、required skills 與 next action 恢復工作，而非只靠 client 內建提示。詳見 Agent Integration 對話框頂部說明與 USER_GUIDE §13.6.1。
Built-in 路徑： 不經 Agent Integration first-run；完成 Agent Preferences（可 Skip）與 Open AI Settings 後即可在 Lantide 內聊天。若團隊日後要接外部 Agent，再從 Header Agent Integration 手動設定。
第一步：選 Quick 還是 Persistent
| 選擇 | 適合情境 | 你要記得的事 |
|---|---|---|
| Quick connection | 一次性測試、只給目前工作區 | 切換工作區不會讓同一份 config 自動改指向新工作區；重新 Expose 沿用同一 lantide-quick-<workspace> key，並以新 credential 更新該 entry |
| Persistent connection | 經常使用同一外部 Agent、希望跨 App 重啟保留設定 | token 只在 Create 或 Rotate 後顯示一次；正常重啟後 client 仍須重新 initialize；server key 為 lantide-<alias> |
第一次只想確認 client 能連上，可以從 Quick 開始。要建立日常工作方式，使用有清楚 alias、expiry 與 scope 的 Persistent connection，比反覆貼一次性設定容易治理。複製的內容一律是具名 entry，貼入 client 時合併既有 mcpServers，不要整檔覆寫。
第二步：先選信任程度，再選 mode
Access mode 是這條 connection 的能力上限，不是 Plan 的分析階段。
| Mode | 能力 | 適合誰先用 |
|---|---|---|
| Observe | 唯讀工作區與 artifacts；不寫入、不暫停內建 Agent | 第一次評估、陪同 review、低信任探索 |
| Execute | 可建立分析 artifacts，正式查詢仍受 Plan review、evidence 與 Report 契約約束 | 分析師用外部 Agent 完成一個明確工作區的正式分析 |
| Admin | Execute 加上高信任的工作區、專案、知識、alias 與本機交付操作 | 已信任 Agent，並需要它協助整理環境或完成管理操作 |
目前 Create connection 表單預設為 All workspaces + Admin。 這是表單預設，不表示第一次試用就該給最高權限。建議依目的分流：
- 低信任或第一次評估：Observe——先確認它看得到正確工作區與 artifacts。
- 正式分析：優先 Single workspace + Execute——把資料邊界鎖在一個工作區，讓 Plan、Approve & Execute、evidence 與 Report 留下完整記錄。若需跨區比較再綁定，可用 All workspaces + Execute（見下一步），但切換工作區會撤銷該 session 的執行授權與待審批項。
- 高信任環境管理：Admin——確認 Agent、操作範圍與回看方式後才使用。
Admin 不代表比較專業，也不代表可以跳過 Plan 或成果審閱。Admin mutation 直通（整理 workspace、patch knowledge 等）≠ 可跳過 Plan lifecycle；但在 Admin 單開工作法下，Plan 的當下審閱可在外部對話完成，Agent 可在你的明確確認後呼叫 claim_plan_approved 推進 Plan → Executing。Execute 雙開仍須在 GUI 按 Approve & Execute。
Plan 核准：三層不要混為一談
| 層次 | 你能期待什麼 |
|---|---|
| Admin mutation 直通 | 高信任的本機設定與 artifact 整理可在 Admin connection 直接執行；仍會留下 Activity 與 audit |
| Admin 單開 + Plan lifecycle | 你在外部對話確認執行後，Agent 可 claim_plan_approved → Plan 變 Executing + scoped grant；之後正式 SQL 仍須帶 execution_plan_ref 才進 Steps |
| Execute 雙開 | 在 Lantide 審 Plan、按 Approve & Execute；Execute connection 不能 claim |
Claim 不是「跳過一切治理」：沒有確認摘要、Plan 非 planning、或 digest 過期都會失敗。事後仍應在 Lantide 核對 Plan Steps、Report、Activity 與 audit。
在 Execute connection，部分 Admin 級操作（如新增資料源）會出現在頂端待審批通知。若該操作需要密文，Approve 會開啟 Connections 並預填非密文字段，你補齊憑證後才算完成；Approve all 遇到這類請求會暫停批次。細節見 USER_GUIDE §13.8。
第三步：選 Single workspace 還是 All workspaces
| Scope | 現在可用的 mode | 適合情境 |
|---|---|---|
| Single workspace | Observe / Execute / Admin | 工作邊界已確定；正式分析優先使用這種 scope |
| All workspaces | Observe / Execute / Admin | Agent 需要先比較工作區，之後再明確選一個；一次只有一個選定的 writer 工作區，不是同時寫多區 |
All-workspaces connection 每次 initialize 都從 unbound 開始：
- 首次
tools/list就是依 Access Mode 固定的精簡 session catalog。核心工具直接呼叫；長尾能力用search_capabilities找到 descriptor，再依invocation使用 read/write invoker。未綁定時，workspace-bound 工具會回WORKSPACE_SELECTION_REQUIRED；綁定後不需重新 list，直接呼叫get_analysis_context。見 USER_GUIDE §13.9。 - 搜尋長尾能力時，Agent 應使用簡潔英文「動作 + 對象」，一次搜尋一個動作。搜尋本身不執行能力，因此一般探索維持
side_effect=any；此欄位篩的是目標能力類型。domain是 optional single enum；確定分類時填一個，不確定則省略，零結果時移除 domain 並改寫一次。外部 Agent 不使用或看見任何activate_*；HTML 與 Execute／Admin 統計能力直接搜尋，統計執行走 write invoker 並保留參數確認、Activity、audit 與 evidence。 - Observe 選定工作區後只做背景唯讀探索，不切換 Lantide GUI，也不排擠既有 writer。
- Execute／Admin 選定工作區後取得該工作區的 writer ownership，預設會切換 Lantide GUI 到該工作區（方便你立刻審閱）。若你明確要求不要打斷畫面，外部 Agent 可關閉 GUI 切換，但仍會綁定 session。切換到另一個工作區時，舊工作區上的執行授權與待審批項會失效——這是「單線雙開」，不是平行多寫。
內建 Ask ≠ MCP Observe： 內建聊天的 Ask 只讓內建 Agent 不改產物；Observe 只約束外部連線。兩者不要混用名稱或設定。見 USER_GUIDE §12.1.1。
- 若另一條 Execute / Admin session 已在寫入，系統不會靜默搶占。外部 Agent 必須先說明阻擋者與風險，取得你的同意後才能指定該 session 重試。
需要去另一個既有工作區時，請改用 All-workspaces profile；不要讓 Agent 建一個新工作區假裝完成切換。並行寫多個工作區時，請改開多條 Single workspace 連線。
Expose、active 與 selected 不是同一件事
| 畫面狀態 | 意思 |
|---|---|
| Profile 已 Exposed | endpoint 已可接受 client；不代表 session 已建立 |
| External session observing（藍色） | Observe session active；內建 Agent 仍可使用 |
| External agent mode enabled（綠色） | Execute / Admin writer active；內建 Agent 在該工作區暫停 |
| All-workspaces unbound | client 已連線，但尚未選工作區 |
| Activity 顯示 Ended | 歷史仍在；不代表 Agent 還連著 |
遇到「已 Expose 但 Header 沒狀態」時，先確認 client 是否重新載入 MCP 並成功 initialize，不要把 waiting 當斷線或把舊 Activity 當 active。
你如何驗收外部 Agent 的工作
外部聊天裡的「我已完成」不是成果依據。建議依序檢查：
- Artifacts——預期的 Plan、SQL、Report 是否真的存在。
- Plan lifecycle——正式分析是否經過 Approve & Execute（Execute 雙開），或 Admin 單開下經
claim_plan_approved且 Activity 有對應紀錄；而不是把探索結果當正式數字。 - Evidence——關鍵數字能否回到正式查詢步驟。
- Report——是否回答問題、包含具體數字與 limitations。
- External MCP Activity——實際呼叫、受影響檔案與
+N/-N是否符合預期。 - Audit / Save History——高信任操作與本機交付是否留下對應記錄。
Activity 中支援安全回退的內容變更會顯示 Undo。系統只在檔案尚未被後續修改時允許 Revert；若內容已變更便阻擋，不會強制覆寫。新建檔回退時會清空內容但保留檔案；Plan lifecycle、export、連線與知識治理等具副作用的操作不能從 Activity 回退。
Activity 隱私與保存
Activity 保存經遮蔽的 host facts、artifact identity 與行數統計，不是外部聊天紀錄，也不把 token 或變更正文放進活動事件。
- Archive：只把 ended session 從日常列表隱藏。
- Clear archived/ended history：實際刪除符合條件的 Activity 與相關 Undo snapshot。
- 清理 Activity 不會刪除 active session、business audit、Plan、Report 或 knowledge。
設定細節與完整按鈕步驟見 USER_GUIDE §13.7。
常見誤區
| 誤區 | 實際 |
|---|---|
| All-workspaces unbound 時 Agent 說「只有管理權限／做不了分析」或「工具很少」 | unbound 是尚未選工作區，而工具較少也是精簡 catalog 的預期結果。先 select_workspace，再 get_analysis_context；不需重新 list。未直接列出的能力用 search_capabilities + 正確 invoker 觸達 |
Approve／claim_plan_approved 後 Progress → Steps 仍是空的 |
正式 SQL／Source Run 必須帶 execution_plan_ref（通常先 read_plan 取最新 digest）才會寫入 Steps；無 ref 的查詢可當 exploration，Steps 不會更新 |
| Header 顯示 Continue，以為 Plan 沒進入 Executing | 在 external lease 下 Continue 多半是預期 UI；請看 Plan 狀態、Progress Steps 與 Activity，不要只靠按鈕文案判斷 |
| Admin 連線就等於可以跳過 Plan 核准 | Execute 雙開仍須在 Lantide 按 Approve & Execute；Admin 單開才可在你明確確認後由 Agent 呼叫 claim_plan_approved，且之後正式 SQL 仍須帶 ref |
安全底線
- MCP host 只綁定本機
127.0.0.1；不要將 config 當遠端 API 分享。 - bearer credential 只放進你信任的本機 MCP client，不貼進 issue、公開聊天室或團隊 wiki。
- 更新 MCP 設定時合併具名 entry，不要用單一 connection kit 整檔覆寫 client 的其他伺服器。
- Unexpose 暫停 endpoint；Rotate 讓舊 token 立即失效並要求更新 client config；Revoke 永久撤銷 profile。
- Persistent token 只顯示一次；建立時就放入合適的本機 secret/config 管理位置。
- Admin 單開是進階工作法。若不即時看 Lantide，仍要在完成後回看 artifacts、Activity 與 audit。
完整設定、關閉視窗與 recovery 操作見 USER_GUIDE §13。
第一次試用檢查清單
- 確認使用的是 Agent Integration，不是 MCP Sources
- 用測試工作區建立一條有 expiry 的 connection
- 低信任評估先選 Observe，確認內建 Agent 仍可使用
- 正式分析優先 Single workspace + Execute；若用 All workspaces + Execute，確認切換工作區後須重新授權／審批
- 在 Lantide 核對 Plan、evidence、Report 與 External MCP Activity
- 演練中斷 session，確認 profile 仍可 Expose 並重新 initialize
- 確認團隊知道誰可以 Rotate / Revoke，以及誰負責 Approve & Execute
下一步
- MCP Sources 入門——需要讓 Lantide 接資料時讀
- 備份、安全邊界與常見問題
- 分析師：Plan → 批註 → Execute → Report
- 平台啟用（數據工程）引言