v1.3.11
Home GitHub

How MCP Tools Behave

Last updated


How tools from connected MCP servers are named, capped, confirmed and kept alive.

Tool naming


MCP-exposed tools are auto-registered with the format:
  1. mcp__<server_name>__<tool_name>

Example: mcp__github__create_issue, mcp__sqlite-notes__read_query.

Image content


Since v1.3.3 image content in a tool result reaches the agent as data URLs: the result becomes a JSON object with image_0, image_1, ... and a text field for any text parts. Error results keep their text only.

Result size cap


Each MCP tool result is capped at 1 MiB. When exceeded, the result is truncated with the marker:
  1. [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:
  • Every MCP tool call goes through the same confirm gate as a built-in tool, under whatever permission mode the request carries (under auto an MCP tool runs without a prompt, like any other tool)
  • 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)

Trust is granted per tool, not per server: /mcp → server → tools (or POST /v1/allowlist with a tool block) replaces the auto-approve entries for one prefix, leaving unrelated rules alone. Every entry must start with that prefix, and prefix* collapses the rest into a whole-server grant. The list lives in ~/.config/agenvoy/allow_tool.

Lifecycle


  • Startup: in the daemon, app.NewMCP runs in a background goroutine after the agent host is set up, so the HTTP server does not wait for slow servers; it calls mcp.New(ctx, sid), then RegisterAll(ctx), then starts Watch(ctx), and clients close on shutdown. Since v1.2.0 only the daemon connects; the TUI reaches these clients over the daemon socket
  • 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. Watch also polls every server's tool list every 60 seconds (30-second timeout per call) for servers that never send the notification, re-registers when the list's signature changes, and renews a client whose session was lost
  • 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 reconnects every client and re-registers tools; /mcp → server → reconnect in the TUI does the same for one server
中文