MCP Client

Agenvoy's MCP client lets agents call tools exposed by any MCP server. Client and server share one package (internal/runtime/mcp) built on the official modelcontextprotocol/go-sdk.

Configuration layout

Two layers — the session layer overrides the global layer:

~/.config/agenvoy/mcp.json                        <- global
~/.config/agenvoy/sessions/<sid>/mcp.json         <- session-scoped

JSON format

{
  "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 and url are mutually exclusive. ${VAR} / $VAR placeholders inside env, headers, and args are expanded with os.Expand at startup.

Transport types

Both transports are handled by the SDK; Agenvoy only supplies the command or the endpoint plus a header-injecting HTTP client.

Management

The add flow asks for the server name, transport (Local stdio / Remote HTTP), the type-specific fields, and the scope. Scope writes one file only — global writes ~/.config/agenvoy/mcp.json, session writes the corresponding ~/.config/agenvoy/sessions/<sid>/mcp.json. There are no agen mcp CLI subcommands.

Tool naming

MCP-exposed tools are auto-registered with the format:

mcp__<server_name>__<tool_name>

Example: mcp__github__create_issue, mcp__sqlite-notes__read_query.

Result size cap

Each MCP tool result is capped at 1 MiB. When exceeded, the result is truncated with the marker:

[mcp output truncated: <total> bytes total, <kept> kept]

This avoids OpenAI Responses API's 10 MB single-tool-output limit triggering a same-signature retry storm. SQLite SELECT * on a large table will hit this — add LIMIT / WHERE.

Confirm behavior

MCP tools route through the most conservative defaults:

• agen cli — confirms each MCP tool call individually
• agen run — auto-approves
• No per-server read_only toggle — Agenvoy does not extend trust to third-party servers because their behavior is unverifiable (a Slack MCP could silently send messages, a Filesystem MCP could silently write files)

For batch operation, use agen run. For ad-hoc usage, accept the per-call confirm cost.

Lifecycle

• Startup: the daemon calls mcp.New(ctx, sid) then RegisterAll(ctx) before building the agent registry, and closes clients on shutdown
• Live tool refresh: clients subscribe to the server's notifications/tools/list_changed and re-register that server's tools when its catalog changes — no restart needed for a server that adds or drops tools
• Server instructions: whatever a server declares as its instructions is surfaced into the agent system prompt, so per-server usage rules reach the model
• Per-server failures: a start or tool-list failure logs a warning and skips that server; core functionality never blocks
• Manual recovery: POST /v1/mcp/reconnect (or /mcp in the TUI) reconnects every client and re-registers tools

Recommended servers

Zero-auth, locally executed (no API key required):

Avoid registering MCP servers whose capabilities overlap with built-in tools (e.g., filesystem, git, fetch, shell) — duplicates only inflate the LLM tool list.