MCP Client

Agenvoy 的 MCP client 讓 agent 得以呼叫任何 MCP server 所暴露的 tool。Client 與 server 共用同一個套件（internal/runtime/mcp），建構於官方 modelcontextprotocol/go-sdk 之上。

設定層級

單一檔案。Session 範圍的層級已移除——所有 client 讀同一份設定：

~/.config/agenvoy/mcp.json

JSON 格式

{
  "servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "remote-api": {
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer ${TOKEN}" }
    }
  }
}

command 與 url 互斥。env、headers、args 內的 ${VAR} / $VAR 佔位符會在啟動時以 os.Expand 展開。

Transport 類型

類型	設定鍵	SDK transport	使用情境
stdio	`command` + `args` + `env`	`CommandTransport`	本地 CLI（`npx`、原生 binary）
Streamable HTTP	`url` + `headers`	`StreamableClientTransport`	遠端服務、長時運行的 MCP server

兩種 transport 皆由 SDK 處理；Agenvoy 只負責提供指令或端點，以及注入 header 的 HTTP client。

管理

工作	TUI	HTTP
列出 server	`/mcp`	`GET /v1/mcp`
新增 server	`/mcp`	`POST /v1/mcp`
移除 server	`/mcp` → 在 server 上按 `d`	`POST /v1/mcp/remove`
連線狀態	`/mcp`	`GET /v1/mcp/status`
重連並重新註冊工具	`/mcp` → server → reconnect（僅該 server）	`POST /v1/mcp/reconnect`（全部 server）
列出已註冊的 MCP 工具	`/mcp` → server → tools	`GET /v1/mcp/tools`
逐工具自動核准	`/mcp` → server → tools	`POST /v1/allowlist` 帶 `tool` 區塊
瀏覽器 OAuth 登入	`/mcp` → server → login / relogin	`GET /v1/mcp/oauth?name=X`（SSE）
預先註冊的 OAuth client	`/mcp` → server → client	`POST /v1/mcp/oauth/client`
清除 OAuth 登入	—	`DELETE /v1/mcp/oauth`

新增流程會詢問 server 名稱、transport（Local stdio / Remote HTTP）與類型專屬欄位。已無 agen mcp CLI 子指令。

HTTP server 的 OAuth

標記 auth: oauth 的 server 透過 mcp.Login 登入：daemon 在 localhost:17988 開啟 loopback callback listener，若供應商允許則執行動態 client 註冊，並把取得的 token 與 client id 存入 OS keychain。供應商拒絕動態註冊時，以 POST /v1/mcp/oauth/client 提供預先註冊的 client（redirect_uri 預設 http://localhost:17988/callback，須與供應商 console 完全一致）。瀏覽器無法連到 listener 時，以 POST /v1/mcp/oauth/callback 把 redirect URL 貼回。

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

Server	用途
`mcp-server-sqlite`	對本地 `.db` 檔執行 SQL
`@modelcontextprotocol/server-memory`	持久化知識圖譜
`@playwright/mcp`	瀏覽器自動化（會下載 chromium）
`@modelcontextprotocol/server-postgres`	本地 Postgres 連線
`mcp-server-time`	時區轉換 / 相對時間