Lantide Data

← 返回学习中心

MCP Sources 入门

读时间： 约 5 分钟 · 系列： 平台启用（数据工程）进阶 · 上一步： 外部 Agent Integration · 下一步： 备份与常见问题

什么时候需要 MCP Sources

这不是 Agent Integration。 MCP Sources 是让 Lantide 连到外部数据服务；右上角 Agent Integration 则是让 外部 Agent 连入 Lantide。若要设定 Cursor、Codex 或 Claude，请读 让外部 AI Agent 安全连入 Lantide。

Connections 管理常见数据库与数据来源（PostgreSQL／MySQL／SQLite、Additional folder、SQL Server／Azure SQL——见 数据源与连线 与 USER_GUIDE §4.5）。MCP Sources 用于透过 MCP 协定接入其他数据或 API，并在侧边栏 物化 成可查的表。

若团队只有直连 DB + 本地 CSV，可以暂不配置 MCP。当分析需求超出 Connections 能挂的来源时，再由你与分析师评估。

你的职责（概要）

  1. MCP Sources 区 齿轮 / ＋ 开启管理
  2. 设定 stdio（启动命令）或 http（URL、Token、Headers）
  3. Test → Add（新增后为 disconnected）
  4. Connect（HTTP 会先验证）直到 connected
  5. 后续可在卡片或来源列右键 Edit／Connect 或 Disconnect／Remove；Edit 不会回显 command、token、headers，请明确保留、替换或清除。
  6. 分析师透过 Start in Chat → Scan Source 或对话探索物化表

Agent 控制（可选）： 内建聊天与外部 Agent（Execute 可 Test／Connect／Explore；Admin 可新增／换凭证／Remove）使用与 Sidebar 相同的来源 registry。凭证永不回显；危险操作需使用者确认。详见 USER_GUIDE §4.6。

完整 UI 与状态见 USER_GUIDE §4.6。

状态怎么看

状态 意味
connected 可用；侧边栏可见物化表
disconnected 已设定未连上
error 最近一次 Connect 失败；看卡片讯息与 Toast

重启 App 或切换回工作区时，系统会对先前已 Connect 的来源各自动尝试重连一轮；失败时显示 error，可再手动 Connect。主动 Disconnect 后不会自动重连。

disconnected / error 时名称旁有 黄色警示；可在来源列右键 Connect。Remove 只移除设定，已物化表保留；若要删除数据，请对物化表使用 Delete。

与分析师分工

  • 你： 来源设定、网路与凭证、Test / Connect
  • 分析师： 扫描来源、决定物化哪些表、在 Plan 里使用

汇出 Workspace 可选包含 MCP cache；汇入后仍须 Reconfigure MCP 并重连。

下载型结果的部署检查

有些 MCP 来源对大查询不直接回传 rows，而是回传短效下载连结或受限 curl GET。Lantide会先把来源回应正规化，再由自己的下载器物化成一般 MCP table；Agent不执行shell，也不能临时放行下载host或私网IP。

正式环境启用前请确认：

  1. 在 MCP Source 设定中填入来源实际使用的 download_hosts；若使用全域部署设定，配置 MCP_DOWNLOAD_ALLOWED_HOSTS。这两者是上限交集，不同 source 不会共用 host 权限。
  2. 私网下载预设封锁。使用者在 sidebar 看到 Review download access 时，可选择只允许这一笔未过期下载，或永久允许该 source 目前的单一 IP（/32 或 /128）。永久授权只会写入该 source，不会放行整个 RFC1918 网段；较宽 CIDR 仅由平台管理员透过 download_private_cidrs 或 MCP_DOWNLOAD_ALLOWED_PRIVATE_CIDRS 配置。
  3. 不要要求 Agent 提供 URL、IP 或 CIDR。下载器会在每次 redirect 重新验证 host/IP，并固定连到已验证 IP，同时保留原 hostname 的 TLS 验证。
  4. 已物化表的 Agent Refresh（侧栏 Agent Refresh）会把 canonical、已脱敏的 mcp_table_info artifact 送进聊天。Agent 依目前 MCP tool schema 自行完成 submit／status／fetch；取得本轮 ready write ID 后，以 mcp_pull_table 覆写本地表（inline／builtin download → mcp_result_id；自订 download 配方 → validate 后的 normalization_id）。Backend 不重播来源，也不保存或重用 task、batch、file handle 或 signed URL；并以 generation CAS 保护并行覆写。有效 ID 期间勿再次 fetch。External agent mode（Execute／Admin）启用时改复制 GUI handoff；数据表 Add to chat 改为 Copy table name。
  5. mcp_pull_table 是唯一写入入口（mcp_materialize_download 为相容 wrapper）。只负责将 Backend 已保存的最终结果安全物化为本地表，不负责远端轮询或推测不同 MCP 工具的关系。来源仍在处理中时，由 Agent 依来源自己的契约继续呼叫 status／fetch；对话中断后不可期待 Backend 自动续跑。
  6. MCP source 凭证与短效 download envelope 使用安装目录（LANTIDEAPP_DATA_DIR）下的稳定 application secret 加密，不依赖每次启动更换的 LANTIDEAPP_AUTH_TOKEN（该 token 仅供本机 API 认证）。删除或迁移整个 data 目录且未一并带走 application_secret 时，须在 UI 重新填入 MCP 凭证。
  7. 以新 task／batch 做单区、多区与非同步来源 smoke：确认能走完「submit → status/fetch → normalization → materialize → Agent Refresh」。Refresh 必须重新 submit 并取得新的结果，不得重用过期 URL 或旧 handle。

常见错误：

错误／状态 处理方式
MCP_REFRESH_UNAVAILABLE Details 显示 Refresh unavailable；Copy rebuild request 后请 Agent 重建表。
normalizer_authoring_required 从表或查询流程启动Agent；Agent会读取短效context、验证declarative normalizer，再继续物化。
normalizer_repair_required 旧表仍可查；使用 Ask Agent to repair download 修复来源shape drift。
DOWNLOAD_HOST_NOT_ALLOWED 管理员确认来源后加入预先设定的download host；不要让Agent或一般使用者临时放行。
private_network_authorization_required 侧边栏会显示 Review download access。选「只允许本次」只重试现有artifact；选「永久允许」仅加入该 source 当前 IP。artifact过期时需重新查询。
DOWNLOAD_ARTIFACT_EXPIRED 重新执行来源查询取得新的短效结果。
MCP_NORMALIZER_INPUT_TOO_LARGE 改用分页、缩小查询scope，或请来源直接提供canonical artifact；不要截断response后重试。

你现在可以做一件事

若暂不需要 MCP，在团队 wiki 注明「目前仅用 Connections」；若需要，先在一台测试机完成 Test → Add → Connect 再推广。

下一步

侧栏 MCP Source 父列可拖到外部 Agent 以对准 alias，再由 mcp_explore 探索；分析指定单一数据表时仍拖底下的物化表。父列拖回内建聊天不插 chip，断线来源的重新连线仍遵守既有权限与确认政策。

← 上一篇: 让外部 AI Agent 安全连入 Lantide下一篇: 备份、安全邊界与常見問題 →