v1.3.11
首頁 GitHub

MCP 工具的行為

最後更新


已連線 MCP 伺服器的工具如何命名、限制大小、確認與維持連線。

Tool 命名


MCP 暴露的 tool 以下列格式自動註冊：
  1. mcp__<server_name>__<tool_name>

範例：mcp__github__create_issue、mcp__sqlite-notes__read_query。

圖片內容


自 v1.3.3 起工具結果中的圖片以 data URL 交給 agent：結果改為 JSON 物件，含 image_0、image_1... 以及文字部分的 text 欄位。錯誤結果只保留文字。

結果大小上限


每個 MCP tool 結果上限為 1 MiB。超過時，結果會被截斷並附上標記：
  1. [mcp output truncated: <total> bytes total, <kept> kept]

這避免觸發 OpenAI Responses API 的 10 MB 單一 tool 輸出上限而引發 same-signature 的 retry 風暴。對大型 table 執行 SQLite SELECT * 會撞到此限制 — 請加上 LIMIT / WHERE。

Confirm 行為


MCP tool 走最保守的預設：
  • 每個 MCP tool call 都經過與內建工具相同的 confirm gate，並依該請求所帶的權限模式決定（auto 下 MCP 工具與其他工具一樣不跳提示直接執行）
  • 無 per-server read_only 開關 — Agenvoy 不對第三方 server 授予信任，因為其行為無法驗證（一個 Slack MCP 可能靜默送出訊息，一個 Filesystem MCP 可能靜默寫入檔案）

信任以工具為單位授予，而非以 server 為單位：/mcp → server → tools（或 POST /v1/allowlist 帶 tool 區塊）只替換某個 prefix 的自動核准條目，其他規則不受影響。每個條目都必須以該 prefix 開頭，prefix* 則收斂成整台 server 的授權。清單存於 ~/.config/agenvoy/allow_tool。

生命週期


  • 啟動：daemon 內的 app.NewMCP 在 agent host 設定完成後於背景 goroutine 執行，HTTP server 不會等待較慢的 server；它呼叫 mcp.New(ctx, sid)、RegisterAll(ctx)，再啟動 Watch(ctx)；關閉時關閉所有 client。v1.2.0 起只有 daemon 建立連線，TUI 經 daemon socket 操作這些 client
  • 即時工具刷新：client 訂閱 server 的 notifications/tools/list_changed，目錄變動時重新註冊該 server 的工具——server 新增或移除工具不需重啟。Watch 另每 60 秒輪詢各 server 的工具清單（每次逾時 30 秒），涵蓋不發通知的 server：清單簽章變動即重新註冊，session 遺失則重建該 client
  • Server instructions：server 宣告的 instructions 會被帶進 agent system prompt，讓各 server 的使用規則直達模型
  • Per-server 失敗：啟動或列工具失敗時記錄 warning 並跳過該 server；絕不阻斷核心功能
  • 手動復原：POST /v1/mcp/reconnect 會重連所有 client 並重新註冊工具；TUI /mcp → server → reconnect 則只針對單一 server
EN