Lantide Data

← 返回學習中心

mcp-sources-basics

讀時間： 約 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. 配置穩定的 LANTIDEAPP_AUTH_TOKEN。變更此值會讓重啟前建立的短效加密 operation 無法解密。
  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 再推廣。

下一步

← 上一篇: external-agent-integration下一篇: backup-security-troubleshooting →