读时间： 約 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 Source 控制（如 Explore、Pull、Test、Connect）。新增来源、替换凭证或 Remove 需要 Admin；Observe 只能读取已物化表与 schema，不能调用远端来源。
什麼时候值得开 Agent Integration
适合：
- 分析師已在 Cursor、Codex 或 Claude 中工作，希望沿用原本的对話介面。
- 團隊仍要求 Plan、SQL evidence、Report 与 Activity 留在 Lantide。
- 你需要一个可查看、可限制、可撤銷的本機 Agent 入口，而不是把资料与憑證交給远端 API。
可以不开：
- 團隊只使用 Lantide 内建 Agent。
- 只是要让 Lantide 读取外部 API；那是 MCP Sources。
- 外部 Agent 跑在另一台機器或云端服务。Agent Integration 綁定本機 loopback，不是远端共享 API。
第一步：选 Quick 还是 Persistent
当支持的 Codex 本机流程开启 Agent Integration 时，可用 Approve & Connect 代替手动复制 connection kit。先在 GUI 检查 scope、mode、expiry、exposure 与本机设置档目的地；只有核准后，Lantide 才会建立 credential 并合并 Codex MCP 设置，credential 不会显示在聊天或 deep link。
| 选擇 | 适合情境 | 你要記得的事 |
|---|---|---|
| Quick connection | 一次性测试、只給目前工作区 | 切換工作区不会让同一份 config 自動改指向新工作区；重新 Expose 会取得新 config |
| Persistent connection | 经常使用同一外部 Agent、希望跨 App 重启保留设定 | token 只在 Create 或 Rotate 后显示一次；正常重启后 client 仍須重新 initialize |
第一次只想確认 client 能連上，可以从 Quick 开始。要建立日常工作方式，使用有清楚 alias、expiry 与 scope 的 Persistent connection，比反覆貼一次性设定容易治理。第一次 tools/list 是固定精简目录；All-workspaces 连接绑定工作区后直接调用 get_analysis_context，不需重新列出工具。长尾能力通过 search_capabilities 与受治理的 read/write invoker 使用。
第二步：先选信任程度，再选 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 留下完整記录。
- 高信任環境管理：Admin——確认 Agent、操作範圍与回看方式后才使用。
Admin 不代表比較專业，也不代表可以跳过 Plan 或成果審閱；它只是允許更多本機操作。
第三步：选 Single workspace 还是 All workspaces
| Scope | 现在可用的 mode | 适合情境 |
|---|---|---|
| Single workspace | Observe / Execute / Admin | 工作邊界已確定；正式分析优先使用这種 scope |
| All workspaces | Observe / Execute / Admin | Agent 需要先比較工作区，之后再明確选一个；不表示同时操作多个工作区 |
All-workspaces connection 每次 initialize 都从 unbound 开始：
- Observe 选定工作区后只做背景唯读探索，不切換 Lantide GUI，也不排擠既有 writer。
- Admin 选定工作区后取得該工作区的 writer ownership，并可让 GUI 切到該工作区。
- 若另一條 Execute / Admin session 已在写入，系統不会靜默搶占。外部 Agent 必須先說明阻擋者与風險，取得你的同意后才能指定該 session 重试。
需要去另一个既有工作区时，请改用 All-workspaces profile；不要让 Agent 建一个新工作区假裝完成切換。
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，而不是把探索结果当正式数字。
- Evidence——关鍵数字能否回到正式查詢步驟。
- Report——是否回答問題、包含具体数字与 limitations。
- External MCP Activity——实际呼叫、受影響檔案与 @@PROTECT0@@ 是否符合预期。
- 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。
安全底线
- MCP host 只綁定本機 @@PROTECT1@@；不要将 config 当远端 API 分享。
- bearer credential 只放进你信任的本機 MCP client，不貼进 issue、公开聊天室或團隊 wiki。
- 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
- 在 Lantide 核对 Plan、evidence、Report 与 External MCP Activity
- 演練中断 session，確认 profile 仍可 Expose 并重新 initialize
- 確认團隊知道誰可以 Rotate / Revoke，以及誰負責 Approve & Execute
下一步
- MCP Sources 入门——需要让 Lantide 接资料时读
- 备份、安全邊界与常見問題
- 分析師：Plan → 批註 → Execute → Report
- 平台启用（数据工程）引言