13. 外部 AI Agent 与 MCP Server
Lantide Data 也可以作为本机 MCP Server，让你惯用的外部 AI Agent（例如 Cursor、Codex、Claude 或其他支持 Streamable HTTP MCP 的客户端）直接使用 Lantide 的数据环境与分析工作面。
外部 Agent 不是取代 Lantide 的 GUI：它在自己的对话中和你协作；Lantide 则保存可查看的 Plan、Report、SQL / evidence、审批、Save History、audit，以及 Agent 实际呼叫 MCP 的活动纪录。这能让「Agent 说它做了什么」与「Lantide 实际留下什么」彼此对照。
不要和 §4.6 的 MCP Sources 混淆。 MCP Sources 是 Lantide 作为 MCP client 接入外部数据或 API；本节的 MCP Server 则是 Lantide 作为 MCP server 供外部 AI Agent 连入。
13.1 何时适合使用
选择外部 Agent 集成，通常是因为你已在某个外部 Agent 中工作，但希望分析不只停留在聊天纪录：
- 想让 Agent 对本机数据进行分析，同时把 Plan、Report 和正式证据留在 Lantide。
- 想在 Claude / Codex 中维持原本的工作方式，但能在 Lantide 审阅执行、成果与活动轨迹。
- 想让高信任 Agent 协助整理工作区、项目、文件别名或知识，仍保留 GUI、audit 与可追溯 artifact。
若你只需要在 Lantide 内完成分析，直接使用内建 AI 助手即可；不必建立 MCP connection。
13.2 打开 Agent Integration
- 在主界面右上角点击 Server Cog 图标，打开 Agent Integration。默认会打开 Persistent connections 标签页。
- 打开顶端的 Enable MCP server。这是全域开关，同时控制 Quick 与 Persistent connections。
- 在 Persistent connections 建立常用连接，或切到 Quick connection 建立仅绑定目前工作区的一次性连接。
Codex 一键配对： 若你从支持的 Codex 本机流程开启 Agent Integration，Lantide 可先带入「配对 Codex」请求。请在 GUI 检查 scope、access mode、expiry、exposure 与设置档目的地后，按 Approve & Connect；只有核准后才建立 credential 并合并 Codex 的本机 MCP 设置。此流程不会把 bearer credential 显示在聊天、deep link、命令列或剪贴簿。若设置写入失败，才改用一次性的 connection kit。
关闭全域开关会立刻停止所有可连入的 MCP endpoint，并 unexpose Quick 与 Persistent connections；已保存的 Persistent profile 设置不会被删除。日后重新打开全域开关时，仍有效且设置为 exposed 的 Persistent connections 会恢复可用。
安全提示： Lantide 的 MCP host 只绑定在本机
127.0.0.1。连接设置包含 bearer credential，请只贴到你信任的本机 MCP client 设置中；不要贴到公开聊天室、issue 或远端主机。外部 Agent 不能自行向 Lantide 要求或重建你的 credential。
13.3 Quick connection：针对目前工作区的一次性连接
Quick connection 适合一次分析、临时使用外部 Agent，或你只想将目前工作区交给它。
- 切换到要使用的工作区。
- 在 Quick connection 标签页选择 Access mode。
- 点击 Expose host。Lantide 会在同一步建立新的 connection credential。
- 点击连接设置旁的 Copy 图标，将 JSON config 贴到外部 Agent 的 MCP 设置。
- 回到外部 Agent，重新加载 MCP 或开始新对话，让它 initialize。
Quick connection 的 credential 只透过 Copy 内容交付；离开这个界面后不会再次显示。若遗失设置，请 Unexpose 后再 Expose，取得新的设置。Quick connection 是 workspace-scoped，切换工作区不会让同一份 config 自动改指向新的工作区。
13.4 Persistent connection：可跨重启使用的连接
Persistent connection 适合经常使用同一外部 Agent，或希望关闭 Lantide 窗口后仍能保留已授权的本机 host。
- 切到 Persistent connections，点击 Create connection。目前建立界面的默认值为 All workspaces + Admin；这是表单默认，不代表所有情境都应选 Admin。第一次评估或低信任的唯读探索可先选 Observe；需要 Plan 审阅与正式证据的单一工作区分析可选 Execute。
- 输入可辨识的 Alias，例如「我的 Codex 分析连接」。
- 选择 Access mode 与 Connection scope：
- Single workspace：选择一个必填工作区；连上后自动绑定该工作区。Access mode 可选 Observe / Execute / Admin。
- All workspaces：可搭配 Observe、Execute 或 Admin。每次连接从未绑定状态开始，由 Agent 明确选择工作区后再进行工作区范围的操作。
- 选择 expiry（1 / 3 / 7 / 30 / 180 / 365 天或 Permanent），并决定是否立即 Expose。
- 建立后复制显示一次的 JSON config，保存到你的 MCP client。
Persistent config 使用安装层级稳定的本机 URL；在正常重启 Lantide 后，已 exposed 且未到期、未 revoked 的 profile 可用同一份 config 重新 initialize。token 只在建立或 Rotate 后显示一次，profile 清单不会回显 token。
| 操作 | 作用 | 对既有外部设置的影响 |
|---|---|---|
| 开关 Expose / Unexpose | 暂停或恢复这个 profile 的 endpoint | Unexpose 后旧设置无法连入；再次 Expose 可继续使用同一 token |
| Rotate | 产生新 token | 你必须将新的 JSON config 更新到 MCP client；旧 token 立即失效 |
| Revoke | 永久撤销 profile | 无法再次打开；请建立新的 connection |
| Remove / Archive（已 revoked） | 从日常清单隐藏已撤销项目 | 不影响既有 audit 或活动纪录 |
| Change local MCP port | 迁移持久 endpoint 的本机 port | token 不变，但所有已复制的 Persistent config 都必须更新 URL |
如果 stable port 被其他程式占用，Persistent connections 会显示 warning，可能包含可辨识的 PID / process name。释放 port 后可按 Retry，不必重启 Lantide；Retry 不会改变 URL。只有你主动使用 Change local MCP port 才会变更 URL。
13.5 Access mode：这是 connection 的能力上限，不是分析阶段
Access mode 在建立 connection 或 Quick connection 时由你选择。它是外部 Agent 能做到什么的能力上限，不会因 Plan 从 planning 变成 executing 而自动切换。
| Mode | 可以做什么 | 适合情境 |
|---|---|---|
| Observe | 唯读 workspace 脉络与 artifacts，不进行写入 | 先理解环境、陪同查看、低风险探索 |
| Execute | 建立或修订分析 artifacts，并以 Plan、review、formal evidence 与 Report 契约完成正式执行 | 需要清楚口径、Plan review 与可追溯分析的工作 |
| Admin | Execute + 高信任的本机设置与组织操作，例如 workspace / project / knowledge / alias，以及已 stage 的结果交付 | 你已信任 Agent、希望它主动整理 Lantide 环境或完成授权的本机操作 |
新建 Quick / Persistent connection 只提供以上三种模式。Draft 已停用，不再提供为新连接选项，外部 Agent 也不应推荐 Draft。
Plan 的 Approve & Execute 只会核准该 Plan 的执行范围与证据脉络，不会把 connection 从 Observe / Execute / Admin 自动升降级。相反地，外部 Agent 也不能自行透过 MCP 提高 access mode 或打开全域 MCP server。
13.6 三种推荐工作法：不是新的 mode
Access mode 是硬性能力边界；以下是 Lantide 建议外部 Agent 依任务与你的偏好采用的工作法。外部 Agent 连上后会读取 playbook，应向你说明目前连接的 scope、能力与推荐做法。
| 工作法 | 适用连接 | 你如何使用 | Lantide 扮演的角色 |
|---|---|---|---|
| Execute 双开 | Execute | 同时开着外部 Agent 对话与 Lantide；在 GUI 审阅 Plan、点 Approve & Execute、查看 evidence / Report | 严谨分析的审阅与可追溯工作面 |
| Admin 双开 | Admin（默认推荐） | 外部 Agent 主导高信任工作，你同步在 GUI 看 artifact、External MCP Activity、Save History 与 audit | 高信任工作的默认共同观察面 |
| Admin 单开（高级） | Admin；且你选择之后回看，并清楚回看时要检查 artifacts／Activity／audit | 主要待在外部 Agent；当下需审阅的说明写在外部对话；必要时关闭 Lantide 窗口，完成后再回来核对成果 | 背景沉淀面：产物品质应与双开对等；不是省略流程 |
这三者不是设置页中的第三个 mode，也不会限制你改变工作方式。Admin 连接时外部 Agent 通常先推荐双开；若你只说「少打扰」或不确定，它应先问你要即时看 Lantide还是之后回看——仅低打扰偏好不足以改推单开。单开是高级工作法：不代表可以省略 Lantide 的分析记录方式；当下审阅在外部对话，回看时在 Lantide 看到的产物与 Activity／audit 应与双开同等完整。若你不确定，直接告诉外部 Agent 你的目标与偏好，或问：「这个连接现在能做什么？我应该怎么用 Lantide？」
13.6.1 外部 Agent 何时建立工作区、项目或切换 Focus
| 概念 | 用途 | 外部 Agent 应如何判断 |
|---|---|---|
| Workspace | 数据、连接、权限与安全边界 | 能安全完成工作就沿用；只有你明确要求、或数据／连接／安全边界不同时才新建。 |
| Project | 可持续追踪的一个分析议题 | 同一业务问题的追问应沿用；需要留下 Plan、Report 或持续迭代时才建立。一次性探索不必硬建。 |
| Focus project | GUI 与 Agent 目前的导览上下文 | 要读写该项目的 artifacts、或你要在 GUI 看它时才切换；它不会改变 workspace、权限或外部 connection scope。 |
| Plan | 正式分析的执行契约 | 需要审阅范围、formal evidence 或可追溯 Report 时建立；不是每次探索都必须建立。 |
外部 Agent 应先读取既有 project、artifacts 和目前 focus，再向你说明组织决策。它不应因为新聊天、暂时没有 activity，或只是偏好整齐就大量建立 workspace / project。
13.7 在 GUI 审阅外部 Agent 的工作
Header 显示的是后端确认的 active session，不是「已 Expose」的设置状态：
- Observe session： 顶端显示蓝色 External session observing。Observe 是唯读连接，不取得 writer ownership，内建 Lantide Agent 仍可使用。
- Execute / Admin writer session： 顶端显示绿色 External agent mode enabled。这表示目前工作区由外部 writer session 操作，内建 Lantide Agent 会暂停，避免两个 Agent 同时修改同一分析脉络。
- Exposed waiting： endpoint/profile 已可接受连接，但尚无 active session；Header 不会把它显示成 connected。请到 Agent Integration 查看 exposed、recovery 或 conflict 等设置状态。
侧边栏工作区列只在该工作区有 active external session 时显示 MCP 状态图标：Observe 使用蓝点，Execute / Admin 使用绿点。它是目前工作的快速提示；完整连接设置、等待与错误处理仍以 Agent Integration 为准。
- 点击 Header 胶囊或 AI 面板中的 Manage 可打开 Agent Integration。
- 胶囊右侧的 link-off 图标是「中断目前 session」。它会结束当前外部 MCP 对话并要求 client 重新 initialize，但不会 unexpose Quick connection、也不会 revoke Persistent profile 或 token。
- 若要真正停止 Quick connection，请在 Quick 标签页按 End external agent mode / Unexpose；若要停止 Persistent connection，请关闭该 profile 的 Expose 开关。
右侧面板的 External MCP Activity 是观测与核对面板，让你确认 Agent 实际呼叫了什么、改了哪些内容，以及在安全条件成立时回退单笔内容变更：
- 每个外部连接建立 logical session；标题显示 profile alias（或 Quick connection）、工作区与 Active / Ended 状态。Activity history 可保留已结束的工作，但不代表 session 仍 active。
- 卡片依时间由上往下新建，记录 initialize、resource read、tool call、policy / review 结果与 connection end。点卡片可展开经过遮蔽的安全摘要。
- 每个成功的 content mutation 各自形成一张 Activity 卡；系统不依时间猜测外部对话回合，也不把多个 tool call 冒充成一个 operation。卡片下方常驻显示受影响的 SQL、Plan、Report、Reference 或 HTML artifact，以及绿色
+N／红色-N行数。点档名可打开 artifact；若它属于另一个工作区，系统会先要求切换，而不会建立错误的空白标签页。 - 支持安全回退的变更右侧显示 Undo 图标。确认 Revert 后，系统只回退该笔 content mutation；回退前会验证目前内容仍等于当时记录的 after hash。若后续已有人工或其他 Agent 修改，会以 content conflict 阻挡，不提供 force revert。
- 新建文件的 Revert 会清空内容但保留文件。Plan lifecycle、execution completion、lineage、export、workspace / connection mutation、knowledge governance 等具副作用的操作不支持由 Activity 回退。成功回退后，原 Activity 仍保留并显示已 reverted，系统另追加回退活动与 audit；不会删掉原历史。
- History（标题右侧时钟图标）可切换过往 session；蓝点只代表该 session 有你尚未看过的非 session-end活动（断线／重启结束本身不计），不代表连接仍 active。蓝点紧贴 profile 名称尾端。列表顶部可选 Mark all as read 一次清除所有蓝点。Ended session 可 Archive（从列表隐藏，但保留纪录直到保留期限到期）。
- 右侧图标列的 External MCP activity icon 在面板收起时，若有尚未看过的 attention 活动会显示红点；打开 Activity 面板后红点隐藏（未读改由 History 蓝点提示）。
- 活动内容会遮蔽 bearer credential、token 与不应显示在观测面板的敏感内容。Activity 不是外部 Agent 的聊天纪录，也不保存变更正文；Undo 所需的受限 before/after snapshot 另行保存在本机。
- 标题列 History 左侧的齿轮图标打开 Activity retention and privacy：
- 从下拉选单设置 Max events per session 与 Ended session retention；保存后立即清除过旧 session 并压缩事件数量。
- Clear archived history (N) 只删除已 Archive 的历史；Clear ended history (N) 删除全部 ended history（含已 Archive 者）。括号显示各自会删除的 session 数量，两者都会同步删除相关 Undo snapshots，且不会清除 active session。
- 上述清理不影响 business audit、artifacts 或 knowledge。设置变更与 Clear 会写入本机 host-level admin audit，不会把敏感正文写进 Activity 事件。
外部 Agent 可打开、focus 或刷新相关 Plan / Report / SQL tab。你仍应以 Lantide 中实际出现的 artifact、Plan steps、Report、Save History、Activity 与 audit 作为成果依据，而不是只依赖 Agent 在外部聊天中的口述。
13.8 Plan、审批、证据与 Admin 操作
Execute connection 的分析流程通常是：Agent 建立或修订 Plan → 请求 GUI review → 你在既有 Plan 工具列按 Approve & Execute → Agent 取得该 Plan 的执行范围 → 在范围内连续执行正式查询与产出 Report。你不需要为 Plan 中每一笔正式 SQL 重复确认。
正式 evidence 会被留在 Plan 的 execution progress。未关联 Plan 的探索查询可以存在，但不应被当成 Report 的关键数字。若 Report 产出后需要补充数据，Agent 可以将 post-execution action 连到 Report，使 Lantide 显示这是正式步骤之外的补充证据；修改 Report 时也能连回对应 evidence。
Admin 操作依 connection mode 具有不同确认方式：
- 在 Execute connection，Admin 级操作会出现在顶端的 pending approval 通知。你可逐笔 Approve / Reject，或选择依序 Approve all；核准后后端才会套用变更。
- 在 Admin connection，Lantide 不会为每笔 Admin 操作要求 GUI confirmation。外部 Agent 仍会收到安全 warning，并应先在自己的对话中取得你的同意；所有操作仍留下 audit 与 Activity。
对于 result export，Agent 会先 stage 完整结果并确认 staging 已完成，才送出 review 或 direct-save。Execute 通常由你在 GUI 核准或按 Save；Admin direct-save 会以已确认、不可被 Agent 任意换掉的 destination 写入，并留下 warning / audit。你可在右侧 Save History 查看 Preparing、Ready to save、Saved、失败或过期等状态；手动 Results 导出仍是原本的本机文件选择流程。
13.9 All workspaces 的选择与切换
All workspaces profile（Observe、Execute 或 Admin）在每次外部 Agent initialize 后都从 unbound 开始，不会暗中沿用上次的工作区。精简目录保持固定；真正要进行工作区范围的操作前，必须明确选择一个工作区，再调用 get_analysis_context。长尾能力通过 search_capabilities 与受治理的 read/write invoker 使用。
Observe（All workspaces）
- 选择工作区后可做唯读探索；不会取得 writer ownership，也不会切换 Lantide GUI 的目前工作区。
- 可与既有 Execute / Admin writer session 并存；不会因为目标工作区已被占用而要求 eviction。
- 不可建立新工作区（
create_workspace_and_select仅 Admin 可用）。
Admin（All workspaces）
- 成功选择或建立工作区后，同一 MCP session 绑定该工作区；Lantide 会同步切换目前 active workspace，刷新侧边栏与该工作区服务。
- 同一 profile 同一时间只可持有一个 Admin writer workspace。
- 若目标工作区已被另一条 writer connection 使用，Agent 会看到占用信息。它必须先在外部对话取得你的同意，并以指定 session 重新送出切换；系统不会静默抢占。被你同意 eviction 的 session 会结束，但该 profile 的 expose / token 设置仍保留。
若你目前使用的是 Single workspace 连接，却需要改去另一个既有工作区，请到 Agent Integration 建立或改用 All workspaces profile，不要请 Agent 用建立新工作区来冒充切换。
13.10 关闭窗口、重新打开与明确退出
如果存在已 exposed 的 Persistent connection，或已 exposed 的 Quick connection，关闭 Lantide 的窗口不一定等于停止 host：Lantide 可保留 backend 与 MCP listener 在背景，让已授权的外部 Agent 不被意外中断，同时销毁 renderer 以减少前端资源使用。
- macOS： 可从 Dock 重新打开窗口。
- Windows： 若有需要保留的 connection，窗口可收合至系统匣；首次在没有保留条件时关闭，会询问你要直接退出或保留在系统匣，并可记住选择。
- 若有未保存内容，会先显示确认：Close window and discard 或 Cancel。
- Quit Lantide、app update、crash 或系统终止会停止 backend / listener；外部 client 的后续请求会 fail closed。下次启动后，仅有效且设置为 exposed 的 Persistent profile 会恢复，client 必须重新 initialize。
13.11 常见问题与安全检查
为什么外部 Agent 连不上？
先确认全域 Enable MCP server 已打开、对应 Quick / Persistent connection 是 exposed、token 未过期／未 revoked。Persistent listener 显示 port collision 时，先释放占用程式后按 Retry；不要自行把 config 改成另一个 port。若你主动 Change local MCP port，必须更新外部 client 里保存的 URL。
为什么外部 Agent 需要重新 initialize？
这是预期的安全语意：app restart、Rotate、Revoke、Unexpose、global disable、明确 Disconnect session 或 workspace eviction 都会让旧 session 失效。重新 initialize 会建立新的 MCP session；这不等于你需要重新建立 profile 或取得新 token（Rotate / Revoke 除外）。
为什么内建 AI 面板不能输入？
只有目前工作区存在 active Execute / Admin writer session 时，内建 Agent 才会暂停以避免互相冲突。Active Observe session 不会阻挡内建 Agent。若 Header 显示绿色 external writer 状态，请让外部 Agent 完成、使用 link-off 中断 session，或结束 / unexpose 外部 connection，再使用内建 Agent。
我的旧 Activity 卡片还在，代表 Agent 还连着吗？
不代表。Activity history 是可追溯纪录；请看 session 的 Active / Ended 灯号。你可 archive 已结束 session，隐藏它的日常列表项目，不会删除 underlying audit。
为什么 connection 已 Expose，Header 却没有 external session？
Expose 只表示 endpoint/profile 已可接受外部 client，可能仍处于 exposed waiting。等 client 重新加载 MCP 并成功 initialize 后，Header 才会显示 active Observe 或 writer session。若长时间没有建立 session，请到 Agent Integration 检查全域开关、profile expiry/revocation、port 状态与 client config。
遇到 recovery 或 writer conflict 时该做什么？
持续性问题会留在 Agent Integration、Header 或相关状态面，不只靠短暂 Toast。依界面提供的主要 action 使用 Retry、Disconnect session、Unexpose、Rotate credential、Select workspace 或 Resolve conflict。Workspace conflict 会先显示阻挡的 writer session；只有你在外部对话明确同意后，Agent 才能指定该 session 重新尝试，系统不会静默驱逐或停用对方的 profile。诊断细节可保留 error code 供回报，但不需要手动修改 sidecar 或猜测 raw MCP 状态。
可以把 Persistent config 给同事或远端服务吗？
不建议。它是本机 loopback endpoint 与本机 bearer credential；它的设计目标是你自己电脑上的可信 MCP client，而不是远端共享 API。若要让别人使用，请在对方的 Lantide 安装上建立自己的 connection。
操作提示： 若遇到连接、recovery 或 client compatibility 问题，请保留不含 credential 的错误码、Activity 截图与重现步骤，再依 §21 回报。