# MCP 工具的行為

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

## Tool 命名

MCP 暴露的 tool 以下列格式自動註冊：

```
mcp__<server_name>__<tool_name>
```

範例：`mcp__github__create_issue`、`mcp__sqlite-notes__read_query`。

## 結果大小上限

每個 MCP tool 結果上限為 **1 MiB**。超過時，結果會被截斷並附上標記：

```
[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，並依該請求所帶的權限模式決定
- 無 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`。

## 生命週期

- **啟動**：`app.NewMCP` 在建立 agent registry 前呼叫 `mcp.New(ctx, sid)`、`RegisterAll(ctx)`，再啟動 `Watch(ctx)`；關閉時關閉所有 client
- **即時工具刷新**：client 訂閱 server 的 `notifications/tools/list_changed`，目錄變動時重新註冊該 server 的工具——server 新增或移除工具不需重啟
- **Server instructions**：server 宣告的 instructions 會被帶進 agent system prompt，讓各 server 的使用規則直達模型
- **Per-server 失敗**：啟動或列工具失敗時記錄 warning 並跳過該 server；絕不阻斷核心功能
- **手動復原**：`POST /v1/mcp/reconnect` 會重連所有 client 並重新註冊工具；TUI `/mcp` → server → reconnect 則只針對單一 server