Add lazy schema loading for MCP tools to reduce token usage#19
Merged
Add lazy schema loading for MCP tools to reduce token usage#19
Conversation
Instead of dumping full schemas for all MCP tools into every model call, tools are registered with truncated descriptions and minimal schemas. A `get_mcp_tool_schema` meta-tool lets the model fetch full schemas on demand before calling a tool. Enabled by default, configurable via `mcp.lazySchemas` and `mcp.maxDescriptionLength` in config or `RA_MCP_LAZY_SCHEMAS` / `RA_MCP_MAX_DESCRIPTION_LENGTH` env vars. https://claude.ai/code/session_01FnU9oVREyZ2kf1npbnHStq
Each MCP tool stub now includes a [serverName] prefix in its description so the model can identify which server provides which tool. The get_mcp_tool_schema meta-tool lists tools grouped by server and returns the server name in its response. Error messages include server attribution. Also adds documentation to README, docs/site (MCP, configuration, tools), and src/mcp/CLAUDE.md. https://claude.ai/code/session_01FnU9oVREyZ2kf1npbnHStq
Instead of a separate get_mcp_tool_schema meta-tool, the first call to each MCP tool now returns the full schema as an error. The model retries with correct parameters on the next call. This eliminates the extra meta-tool and simplifies the two-level tool calling to normal error handling that LLMs already understand. https://claude.ai/code/session_01FnU9oVREyZ2kf1npbnHStq
Each tool closure only tracks its own state, so a boolean is sufficient. https://claude.ai/code/session_01FnU9oVREyZ2kf1npbnHStq
Tool names become `serverName__toolName` to avoid conflicts across servers. Descriptions are passed through unchanged from the MCP server. Removed maxDescriptionLength config option and truncation logic — only inputSchema is stripped for lazy loading. https://claude.ai/code/session_01FnU9oVREyZ2kf1npbnHStq
…compat - prefixToolName() applies to both lazy and non-lazy paths in client.ts - Server names sanitized to [a-zA-Z0-9_] (e.g. my-server → my_server) - Inlined formatSchemaHint for conciseness - Added prefixToolName and sanitization tests https://claude.ai/code/session_01FnU9oVREyZ2kf1npbnHStq
The test looked up tools by bare name 'greet' but tools are now registered as 'test_stdio_server__greet'. https://claude.ai/code/session_01FnU9oVREyZ2kf1npbnHStq
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements lazy schema loading for MCP tools to reduce token consumption when working with many tools. Instead of sending full tool schemas to the model upfront, tools are registered with truncated descriptions and minimal schemas. The model can request full schemas on-demand via a new
get_mcp_tool_schemameta-tool before calling a tool.Key Changes
wrapMcpToolsLazyfunction (src/mcp/lazy-tools.ts): Wraps MCP tools with lightweight stubs containing only name and truncated description. Full schemas are stored internally and retrieved via the meta-tool.get_mcp_tool_schema: Allows the model to fetch the complete description and parameter schema for any MCP tool by name. Returns helpful error messages listing available tools if an unknown tool is requested.McpClient.connect(): AddedMcpConnectOptionsparameter to support lazy schema loading. Tools are either wrapped lazily or registered directly based on thelazySchemasoption.lazySchemas(boolean, default:true) andmaxDescriptionLength(number, default:100) to MCP config. These can be set via environment variables (RA_MCP_LAZY_SCHEMAS,RA_MCP_MAX_DESCRIPTION_LENGTH).Implementation Details
...if truncatedget_mcp_tool_schemahttps://claude.ai/code/session_01FnU9oVREyZ2kf1npbnHStq