[FEATURE] Automatic File Writing for Large MCP Responses

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

Feature Request: Automatic File Writing for Large MCP Responses

Problem Statement

When MCP tools return large responses (e.g., extensive search results, large documents, bulk data), they consume significant context window space. While Claude Code provides MAX_MCP_OUTPUT_TOKENS to configure limits, large responses can still:

1. Exhaust context budget - Reduce available tokens for actual work
2. Reduce readability - Make conversation history harder to navigate
3. Impact performance - Large inline responses slow down processing

Current Behavior

• MCP responses are always included inline in the conversation
• Warning displayed at 10,000 tokens
• Hard limit at 25,000 tokens (default, configurable via MAX_MCP_OUTPUT_TOKENS)
• Only options: increase limit or ask MCP servers to paginate

Proposed Solution

Proposed Solution

Add automatic file writing for large MCP responses with configurable threshold:

Configuration Options

# Enable automatic file writing for large MCP responses
export MCP_AUTO_WRITE_TO_FILE=true

# Threshold for writing to file (default: 10000 tokens)
export MCP_FILE_WRITE_THRESHOLD=10000

# Directory for MCP response files (default: .claude/mcp-responses/)
export MCP_RESPONSE_DIR=".claude/mcp-responses/"

Behavior

When an MCP tool response exceeds MCP_FILE_WRITE_THRESHOLD:

1. Write response to file: {MCP_RESPONSE_DIR}/{timestamp}-{tool_name}.txt
2. Return file reference: Instead of full content, return:

```
[Large MCP response written to file: .claude/mcp-responses/2026-01-23T10-30-45-mcp__google__search.txt]

Summary: Retrieved 1,247 search results (45,231 tokens)
File size: 180 KB
```

1. Claude can read file: Claude Code can use Read tool on the file as needed
2. Preserve full data: Nothing is lost, just relocated to optimize context

Benefits

1. Context Window Efficiency

• Save tokens for actual code analysis and generation
• Enable longer conversations without hitting limits
• Reduce need for conversation summarization

2. Better User Experience

• Cleaner conversation history
• Faster response times
• Easier to scroll through chat

3. Preserved Data Fidelity

• Nothing is lost or truncated
• Full data available for selective reading
• Can be referenced later in conversation

4. Flexibility

• Users choose threshold based on their needs
• Can be disabled entirely if not wanted
• Works alongside existing MAX_MCP_OUTPUT_TOKENS

Implementation Notes

File Naming Convention

{MCP_RESPONSE_DIR}/{timestamp}-{server_name}__{tool_name}.{ext}

Examples:
.claude/mcp-responses/2026-01-23T10-30-45-mcp__google__search.txt
.claude/mcp-responses/2026-01-23T11-15-22-mcp__gsheets__get_values.json

File Format

• Preserve original response format (JSON, text, etc.)
• Add metadata header:

```
// MCP Response Metadata
// Server: mcp-google
// Tool: search
// Timestamp: 2026-01-23T10:30:45Z
// Token Count: 60,231
// Original Query: [query parameters]
// ---

[actual response data]
```

Cleanup Strategy

• Files older than 7 days automatically cleaned (configurable)
• Or keep files for current session only
• User can manually clean via rm -rf .claude/mcp-responses/

Integration with Existing Features

• Works alongside MAX_MCP_OUTPUT_TOKENS
• Respects existing MCP tool permissions
• Files written to .claude/ directory (git-ignored by default)

Use Cases

1. Large search results - Glean/Sourcegraph searches returning hundreds of results
2. Bulk data exports - Spreadsheet data, database queries
3. Documentation retrieval - Full API docs or multiple wiki pages
4. Code search - Extensive grep/search results across large codebases
5. Log analysis - Large log file contents from MCP servers

Related Issues/Documentation

• Current behavior: MAX_MCP_OUTPUT_TOKENS environment variable
• Related: Context window management strategies
• See also: MCP server pagination recommendations

Additional Context

• Environment check shows MAX_MCP_OUTPUT_TOKENS is not currently set
• Use case: Working with enterprise search (Glean) often returns large result sets
• Current workaround: Manually increase token limit, but wastes context

---

Alternative Solutions

Alternative Approaches Considered

Alternative 1: Streaming/Pagination in MCP Protocol

• Pros: Server-side control, potentially more efficient
• Cons: Requires MCP server changes, not all servers may support it
• Note: This could complement file writing, not replace it

Alternative 2: Aggressive Summarization

• Pros: Keeps everything in conversation context
• Cons: Information loss, may miss important details
• Note: Summarization could work with file writing (summarize before deciding to write)

Alternative 3: Manual File Management

• Pros: User has full control
• Cons: Extra manual steps, context already consumed before writing
• Note: Not ideal for automatic MCP responses

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

Example Workflow

# User asks for broad search
User: "Search Google for all articles about Rick A."

# MCP returns 50 documents with full content (60,000 tokens)
# Instead of inline dump:
Claude sees:
  [Large MCP response written to: .claude/mcp-responses/2026-01-23T10-30-45-mcp__google__search.txt]
  Summary: 50 documents found (60,231 tokens)

# Claude can now:
1. Read the file selectively (e.g., first N lines)
2. Parse and extract only relevant parts
3. Present summary to user without context waste

Additional Context

_No response_