# MCP Server

透過 stdio pipe 啟動時，`agen` 會作為 MCP server 執行。任何相容 MCP 的 agent（Claude Code、Codex、OpenCode 等）都可連線並使用 Agenvoy 的工具 — 包含即時建立新工具。

## 外部 agent 能獲得什麼

- **沙箱化執行** — 所有 script 工具都在 OS 原生 sandbox（macOS `sandbox-exec` / Linux `bwrap`）內執行，隔離 `~/.ssh`、`~/.aws`、`.env`、`*.pem` 等敏感路徑
- **自動建立工具** — 當現有工具都無法涵蓋需求時，agent 呼叫 `tool_generate_guide` 取得 build contract，再 `edit_tool(mode=write)` → `test_tool` 建立新的 script 或 API 工具。工具會被持久化並可跨 session 重用
- **共享工具庫** — 任何 agent（Agenvoy 內部、Claude Code、Codex 等）建立的工具都會存至 `~/.config/agenvoy/tools/script/`，並對所有已連線的 agent 可用。建立一次，處處可用
- **即時資料存取** — `api_public_api_list` 索引免費的公開 API；agent 挑選其一，圍繞它 scaffold 出一個 script 工具，並以真實資料而非訓練知識的臆測作答

## 快速設定

TUI 沒有安裝精靈（`/mcp` 沒有 `install` 動作）；請手動把設定寫入你的 agent 設定檔。

各 agent 的配置：

**Claude Code** — `~/.claude.json`
```json
{ "mcpServers": { "agenvoy": { "command": "agen" } } }
```

**Codex** — `~/.codex/config.toml`
```toml
[mcp_servers.agenvoy]
command = "agen"
```

**OpenCode** — `~/.config/opencode/opencode.jsonc`
```json
{ "mcp": { "agenvoy": { "type": "local", "command": ["agen"] } } }
```

## 通用 MCP client 設定

對於上方未列出的任何 MCP client，唯一的要求是：

- **Transport**：stdio（透過 stdin/stdout 的 JSON-RPC）
- **Command**：`agen`
- **Args**：無
- **前置條件**：`agen` binary 位於 `$PATH`（`curl -fsSL https://agenvoy.com/scripts/install.sh | bash`）

Server 使用 [MCP 協定版本 `2024-11-05`](https://spec.modelcontextprotocol.io/specification/2024-11-05/)，支援 `tools/list`（含 `listChanged` 通知）與 `tools/call`。無需驗證 — server 以目前使用者身分在本地端執行。

各 MCP client 常見的配置模式：

```json
{
  "<servers_key>": {
    "agenvoy": {
      "command": "agen"
    }
  }
}
```

其中 `<servers_key>` 依 client 而異（`mcpServers`、`mcp_servers`、`mcp` 等）。部分 client 需要明確的 `"type": "stdio"` 或 `"type": "local"` 欄位。請查閱你的 client 文件。