Dify 自訂工具 / MCP:把系統接進 agent,還要驗得穿

前兩篇我們讓自架的 Dify agent 學會上網查、也 查自己的文件。這一篇更進一步:讓它接進你「會變動、能做事」的系統——ERP、訂單、庫存。這一步,才是 agent 從「會聊天」變成「真的幫你辦事」的關鍵。我用一個假的訂單 API 練手,再接一個真的內部系統,把整條路和一路踩到的坑一次講清楚。

agent 碰不到你的活系統

先看 agent 的能力邊界。聊天靠模型舊知識、搜尋只到公開網路、RAG 只到你上傳的靜態文件。但「這張訂單出貨了嗎、追蹤碼多少」這種答案,只活在你的系統裡、而且每天在變。要拿到它,就得把系統包成一個 agent 能呼叫的工具。

包成工具 = 一份 OpenAPI 說明書

怎麼包?你給 Dify 一份 OpenAPI 說明書,其實只講四件事。貼進 Dify 的「自訂工具」,它就解析成一個 agent 能呼叫的工具:

{
  "openapi": "3.1.0",
  "info": {"title": "訂單查詢系統", "version": "1.0.0"},
  "servers": [{"url": "https://your-system.example.com"}],
  "paths": {
    "/order": {
      "get": {
        "operationId": "query_order",
        "summary": "查詢訂單狀態",
        "description": "用訂單編號查商品、數量、狀態、出貨日、追蹤碼",
        "parameters": [
          {"name": "id", "in": "query", "required": true,
           "description": "訂單編號,例如 A1001", "schema": {"type": "string"}}
        ]
      }
    }
  }
}

說明書要講的	對應	為什麼 agent 需要
① 系統在哪	servers.url	要知道去哪打
② 有什麼動作	GET /order	這是「查訂單」這個能力
③ 要給什麼參數	id(訂單編號)	要知道該帶什麼
④ 這動作叫什麼、幹嘛	description	agent 靠這句判斷該不該用——寫含糊就自己亂編

鐵律:三方獨立驗證

工具接好、agent 答得漂亮,先別急著相信。用三方獨立證據交叉驗證,才知道它是真查、還是在唬爛:

證據來源	看什麼
你系統的存取紀錄	請求真的進來了嗎——來源 IP 對不對
Dify 資料庫 message_agent_thoughts	工具真的被呼叫了嗎、observation 拿回什麼
agent 的答案	有沒有出現它編不出來的真資料(如追蹤碼 SF9931002)

為什麼要三方對:模型可能沒呼叫工具就亂編(查資料庫一眼看穿),也可能有呼叫、有拿到真資料卻在總結時改寫——後者表面全對,只有把「工具原始回傳」跟「最終答案」擺一起才抓得到。

坑一:SSRF 擋掉內部系統

接真系統的第一道牆:Dify 為了資安,預設封鎖對「私有 IP」的呼叫。而你公司的 ERP、資料庫幾乎都在內網,所以「讓 agent 接內部系統」第一步一定撞到這道 SSRF 防護。解法兩種:在設定裡放行你信任的內網位址,或讓系統走一個有有效憑證的公開網域(HTTPS 443)——後者最順,還順帶避開非 443 埠與自簽憑證的麻煩。這一條,是「給公司所有人用」時每個內部系統都會遇到的關卡。

坑二:登入 token 會過期

第二個坑是認證。真系統通常要先登入拿一把 token,而 token 會過期——貼死一個進去,大概一小時後就斷,工具整個掛掉。正規解法是做一層自動換 token 的代理;但更省事的是,很多企業系統其實提供「給整合用、不會過期的長效金鑰」。接真系統前先問一句:這個系統有沒有長效整合金鑰?找到它,這個難題直接消失。

最陰險的坑:工具成功 ≠ 答案正確

第三個坑最陰險,也最容易被騙過去。前兩種幻覺(沒呼叫工具就亂編)你查紀錄就抓到;但這一種不一樣:工具有呼叫、有拿回真資料,可是模型在最後總結那一步,還是把內容改寫、甚至換成完全不同的東西。表面一切正常——有呼叫紀錄、有真回傳,答案卻是假的。能力較弱的小模型、尤其在一般電腦上跑本機時,特別容易犯這種錯。這時你要的不是更聰明的 prompt,而是換一種架構。

Agent vs Chatflow:錯不得的資料

關鍵是分清楚兩種做法。用 Agent 讓模型自由呼叫工具、再自由總結——彈性大,但總結那步模型有機會改寫、有機會幻覺。換成 Chatflow:工具參數寫死,查完直接把原文吐出來,中間完全不經過模型總結。

	Agent(自由呼叫+總結)	Chatflow(寫死+忠實呈現)
特性	彈性大、能對話	一字不差、流程固定
風險	總結那步可能改寫/幻覺	零改寫
適合	探索式、容錯、要來回對話	財務 / 醫療 / 法遵等「錯不得」的資料

Chatflow 忠實版三節點

Chatflow 的忠實版其實很簡單,三個節點:開始 → 工具(參數寫死) → 直接回覆。兩個重點:(1) 工具參數直接填死,不讓模型插手;(2)「直接回覆」一定要指向「工具的輸出」,不是某個模型節點——這是最容易接錯的地方。如果原始資料是一包 JSON、看起來很醜,再加一個模板轉換節點純排版、一個字都不改。整條線走完,你得到的就是你系統裡的真資料,原封不動、排整齊。

反過來:把 Dify app 用 UI 開成 MCP server(實測)

前面整篇都在講 Dify 怎麼「呼叫」工具與 MCP(出)。這一段補上反方向——把你的 Dify app 開成 MCP server,讓別的 AI(Claude、Cursor…)當工具用(入)。全程用 UI、而且跨機器實測通過。

這版沒有原生按鈕 → 裝外掛

先說一個實測踩到的事實:這版 Dify 的「發佈」下拉、app「概覽」頁,任何 app 型別都找不到 MCP 發佈開關。官方正規的 UI 做法是裝外掛:外掛 → Marketplace 搜 mcp-server(說明「make dify’s workflow as a MCP server」)→ 安裝。

設定端點:4 個欄位

欄位	填什麼
App	選你要對外開放的 app
App Type	只有 Chat / Workflow 兩種
App Input Schema	要填一整個 MCP 工具定義 JSON(name / description / inputSchema),不是只填參數
Auth Bearer Token	設一個當密碼(MCP 網址=等於 API key)

App Input Schema 的正確格式(以訂單查詢為例):

{
  "name": "query_order",
  "description": "查詢訂單狀態,回傳原文",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {"type": "string", "description": "使用者問題"}
    },
    "required": ["query"]
  }
}

關鍵限制:Agent 型開不了,只有 Chat / Workflow

App Type 只有 Chat 和 Workflow。Agent 型硬選會失敗,回 Agent Chat App does not support blocking mode——因為 Agent 是多步 ReAct、只能「串流」回應,而外掛用「blocking(等完整答案)」呼叫,對不上。所以想對外開成 MCP,就把邏輯做成 Chatflow(它能掛工具、能忠實呈現、又支援 blocking)。

拿到網址 + 跨機器實測

存檔後得到端點網址 /e/<id>/mcp(還有 /sse)。它可能顯示成 localhost——那只是 Dify base URL 沒設,把主機換成你的公開網域就對外通。實測:另一台機器上的 AI,用 MCP client 連進來 → initialize → tools/list 看到工具 → tools/call → 跑你的 Chatflow → 拿到結果。「別的 AI 把你的 Dify 當工具用」整條跑通。

一句話心法

把系統包成工具不難,難在別被漂亮的答案騙了。接得到是第一步,更重要的是驗得穿——用系統紀錄、平台資料庫、還有「模型編不出來的真資料」去確認它是真查還是唬爛。而對錯不得的資料,寧可用最笨、最忠實的 Chatflow,也不要一個會改字的聰明 agent。