Why
Attaching a fat MCP server (some expose 50+ tools) floods the model's context with tool schemas it mostly won't use — slower, costlier, and it degrades tool selection.
What
Progressive MCP tool disclosure:
- When total MCP tool count exceeds a threshold (config, default ~15), stop inlining all MCP schemas. Instead expose two meta-tools:
search_tools(query) — fuzzy-search attached MCP tools by name/description, returns top matches with their schemasuse_tool(name, arguments) — invoke a discovered tool by its namespaced name
- Below the threshold, keep current inline behavior
- Permission prompts must show the real underlying tool name, not
use_tool
Where to start
- MCP client + tool registration:
src/mcp/client.ts, tool schema assembly in src/tools/index.ts
- Namespacing is already
server__tool
Acceptance criteria
- With a many-tool MCP server attached, request payload shrinks (assert schema count), and the agent can still discover + invoke a tool end-to-end
- Threshold configurable; typecheck + tests green
Why
Attaching a fat MCP server (some expose 50+ tools) floods the model's context with tool schemas it mostly won't use — slower, costlier, and it degrades tool selection.
What
Progressive MCP tool disclosure:
search_tools(query)— fuzzy-search attached MCP tools by name/description, returns top matches with their schemasuse_tool(name, arguments)— invoke a discovered tool by its namespaced nameuse_toolWhere to start
src/mcp/client.ts, tool schema assembly insrc/tools/index.tsserver__toolAcceptance criteria