# How MCP Tools Behave

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

## 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:

- Every MCP tool call goes through the same confirm gate as a built-in tool, under whatever permission mode the request carries
- 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