Skip to content

Meta tools

Vladimir Kochnev edited this page Nov 17, 2026 · 1 revision

Meta tools

A set exposes nine MCP tools: five work with downstream servers, four serve their resources and prompts. The downstream catalog is never listed — a client reaches it through invoke_command.

tool what it returns
list_servers inventory: type, health, tags, approval mode
list_commands tool names of one server, or of several at once
describe_commands input schema of the named tools, plus missing
invoke_command the result of one downstream tool
invoke_many up to 8 independent calls in one request
list_resources resources of the servers that expose them
read_resource one resource
list_prompts prompts of the servers that expose them
get_prompt one prompt rendered with arguments

A refusal is an ordinary tool result with isError: true and one text item starting Error: — the MCP call stays up. The four resource and prompt tools answer only for a server whose config names the surface in expose.

Reading an answer

  • list_servers probes 8 at a time, 15 s timeout, 15 s cache that remembers failures. unknown: true means the probe never started (no free slot), so healthy: true reads "not sick", not "checked". env and headers never appear.
  • list_commands takes {"server": "a"} or {"servers": ["a","b"]}, plus prefix, namesOnly and maxBytes. One failed server does not hide the others: its value is {"error": "…"}.
  • describe_commands takes server and command_names, both required. missing is always present and lists names the server does not expose; they do not fail it.
  • invoke_command takes server, command_name (alias command) and parameters; any other top-level key is refused, so a call cannot silently run empty.
  • invoke_many returns one entry per call, in the order of calls, not in completion order: ok, result or error, ms, timeout_ms. At most 4 calls hit one downstream server, 8 run in total. Bad input (no calls, more than 8, an unknown key inside a call, parameters that is not an object, a bad maxBytes) fails the whole request and runs nothing; a partial failure stays data with ok: false.

Timeouts

timeoutMs is per call, 1000 to 600000 ms; 0 or absent means the set's requestTimeout, and an out-of-range value is refused before anything runs. A call reports _meta.timeoutMs — the limit it actually ran under; invoke_many reports the fan-out budget there.

Truncation

maxBytes defaults to 32768 for invoke_command, invoke_many and read_resource (at most 1048576); the four catalog tools cut nothing unless it is given.

A JSON answer is cut structurally, so it stays one valid document: the longest strings are shortened first, a string of 32 bytes or less is kept as it is, and the cut is recorded inside the document — an object gains _truncated, an array one last string element. With nothing to shorten, the answer is cut raw at a UTF-8 boundary and ends with [обрезано: 32768 из 149873 байт, полный ответ — …]. The whole answer is written 0600 under ${MCPRIG_DATA_DIR:-$TMPDIR}/tool-out/; over HTTP a set hands it out under /tool-out/<name> with the same key as /mcp. An answer within the cap is returned untouched.

Call describe_commands before invoke_command: it is the only place the parameter schema is visible, and a guessed name or a misplaced argument is the usual cause of a refusal. Use namesOnly on a large server — hundreds of tools cost tens of KB, names about a sixth of that.

Details: docs/en/meta-tools.md.

Clone this wiki locally