[FEATURE] Add MAX_MCP_TOOL_SCHEMA_TOKENS configuration option

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When using Claude Code with many or large MCP tool schemas, the cumulative token count of tool definitions can overwhelm the available LLM context window, leaving insufficient space for user code, task descriptions, and instructions. Currently, Claude Code has MAX_MCP_OUTPUT_TOKENS to control tool output size, but no equivalent control exists for the input schemas themselves. This creates a context management gap where users cannot effectively balance tool availability with context preservation for their actual work.

Proposed Solution

Add a MAX_MCP_TOOL_SCHEMA_TOKENS configuration option that mirrors the existing MAX_MCP_OUTPUT_TOKENS functionality, but controls the cumulative token count of MCP tool schemas included in the context.

Implementation Details:

• Configurable in .claude/settings.json or as an environment variable MAX_MCP_TOOL_SCHEMA_TOKENS
• When the total token count of all loaded MCP tool schemas exceeds this limit, Claude Code displays a clear warning (similar to the current output token warning)
• Excess schemas are collapsed to summary form showing only function names and brief descriptions, preserving tool availability while reducing context consumption
• Uses the same token counting methodology as the existing MAX_MCP_OUTPUT_TOKENS feature for consistency

User Experience:
Users would set their desired schema token budget (e.g., 5000 tokens) and receive clear feedback when schemas are being summarized due to the cap. This provides immediate, user-controllable context management without requiring complex tool selection logic.

Alternative Solutions

Currently, users must either:

1. Manually disable MCP servers entirely, losing valuable functionality
2. Accept reduced context space for user code and tasks
3. Use smaller MCP tool sets than desired

None of these options provide the granular control needed to balance tool availability with context efficiency.

Priority

Medium - Would be very helpful

Feature Category

MCP server integration

Use Case Example

A developer has configured Claude Code with multiple MCP tools: a database tool with 50+ functions, browser automation with extensive APIs, file operations, and Git integration. When they ask Claude Code to analyze a 200-line Python function, they see a warning that tool schemas are consuming 8,000 tokens of the available context.

Steps with the new feature:

1. Developer sets MAX_MCP_TOOL_SCHEMA_TOKENS: 3000 in their .claude/settings.json
2. Claude Code displays: "Warning: MCP tool schemas capped at 3,000 tokens (was 8,000). Database and browser tools summarized."
3. Full schemas are kept for file system and Git tools, while database/browser tools show only function names and brief descriptions
4. This frees up 5,000 tokens for the actual code analysis task
5. Claude Code can now include more of the user's code and provide more detailed analysis

The developer maintains access to all tools but gets much better context utilization for their specific task.

Additional Context

Precedent: Existing MAX_MCP_OUTPUT_TOKENS Behavior

Claude Code already provides MAX_MCP_OUTPUT_TOKENS to limit the maximum tokens allowed in MCP tool responses, with a default warning at 10,000 tokens. This setting effectively controls excessively large outputs from tools and demonstrates the established pattern for token-based MCP management.

Natural Extension to Schema Management

The proposed MAX_MCP_TOOL_SCHEMA_TOKENS feature is a direct analog to this existing functionality, applying the same principles to input schemas rather than output responses. This maintains consistency with Claude Code's existing MCP token management approach while addressing the complementary problem of context consumption by tool definitions themselves.

Implementation Alignment

• Uses the same token counting methodology as MAX_MCP_OUTPUT_TOKENS for consistency
• Provides similar warning messages when limits are exceeded
• Follows the same configuration patterns (settings file and environment variables)
• Maintains backward compatibility with existing MCP tool servers

This feature completes the MCP token management system by providing user control over both input (schemas) and output (responses), enabling much better total context preservation and overall usability in projects with many complex MCP tools.