# MCP Client

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

## 設定層級

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

```
~/.config/agenvoy/mcp.json
```

### 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 貼回。

## 推薦 server

零認證、本地執行（不需 API key）：

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

避免註冊能力與內建 tool 重疊的 MCP server（例如 `filesystem`、`git`、`fetch`、`shell`）— 重複只會膨脹 LLM 的 tool 清單。