Skip to content

Optimize MCP Tool Context: Reduce client memory overhead by 57%

🎯 Optimize MCP Tool Context: Reduce client memory overhead by 57%

📊 Problem Statement

The GitLab MCP server currently sends ~52,000 characters of tool definitions to clients on every connection, causing:

  • Excessive memory consumption in AI clients
  • Slower initial connection establishment
  • Inefficient token usage in LLM interactions
  • Poor developer experience with 75 unorganized tools

Current Overhead Breakdown

  • 75 tools averaging 693 characters each
  • Verbose descriptions with repetitive phrases
  • Redundant JSON Schema metadata ($schema, additionalProperties)
  • Unoptimized parameter descriptions
  • No logical tool organization

🚀 Proposed Solution

Implement a three-phase optimization strategy to achieve 57% context reduction (52,000 → 22,500 characters) while maintaining full functionality.

📋 Implementation Plan

Phase 1: Description Standardization (40% reduction)

Timeline: 1-2 days
Impact: 8,000 characters saved

Tasks

  • Audit all 75 tool descriptions in src/server/tools.ts
  • Remove redundant "GitLab repository" qualifiers
  • Standardize CRUD operation descriptions
  • Apply consistent description patterns

Description Pattern Standards

Before: "Create a new merge request in a GitLab repository" (47 chars)
After:  "Create merge request" (20 chars) - 57% reduction

Before: "Get the contents of a file from a GitLab repository" (51 chars)
After:  "Get file contents" (17 chars) - 67% reduction

Phase 2: Schema Optimization (29% reduction)

Timeline: 2-3 days
Impact: 15,000+ characters saved

Tasks

  • Create custom zodToJsonSchema wrapper to strip metadata
  • Extract common schema patterns to src/schemas/common.ts
  • Implement schema composition for shared patterns
  • Compress parameter descriptions

Optimization Targets

  • Remove $schema declarations (4,050 chars)
  • Remove additionalProperties: false (2,400 chars)
  • Simplify parameter descriptions (e.g., "Project ID or path" vs verbose version)
  • Extract ProjectParamsSchema used in 60+ tools

Phase 3: Tool Organization & Categorization

Timeline: 1-2 days
Impact: Improved client UX and progressive loading capability

Tasks

  • Implement resource-based tool categorization
  • Add category metadata to tool definitions
  • Enable progressive tool discovery
  • Create category-based filtering mechanism

Proposed Categories (75 tools → 6 groups)

repositories:     # 7 tools
  - files: create_or_update_file, get_file_contents, push_files
  - repos: search_repositories, create_repository, fork_repository
  - branches: create_branch, get_branches, protect_branch

issues:          # 13 tools
  - crud: create_issue, get_issues, update_issue, delete_issue
  - comments: get_issue_notes, create_issue_note, update_issue_note
  - time: add_time_spent, get_time_stats, set_time_estimate

merge_requests:  # 16 tools
  - crud: create_merge_request, get_merge_requests, update_merge_request
  - operations: merge_merge_request, approve_merge_request, rebase_merge_request
  - comments: get_merge_request_notes, create_merge_request_note

ci_pipelines:    # 14 tools
  - pipelines: get_pipelines, create_pipeline, retry_pipeline
  - jobs: get_jobs, cancel_job, play_job, retry_job
  - variables: get_variables, create_variable, update_variable

ci_operations:   # 7 tools
  - artifacts: get_job_artifacts_list, download_job_artifact
  - logs: get_job_log
  - config: validate_ci_config

project_mgmt:    # 8 tools
  - milestones: create_milestone, get_milestones, update_milestone
  - labels: create_label, get_labels, update_label

🔧 Technical Implementation

Configuration

Add environment variable support for opt-in optimization:

MCP_OPTIMIZE_CONTEXT=true     # Enable all optimizations
MCP_COMPACT_DESCRIPTIONS=true # Enable description compression only
MCP_COMPACT_SCHEMAS=true      # Enable schema optimization only
MCP_TOOL_CATEGORIES=true      # Enable tool categorization

Files to Modify

  • src/server/tools.ts - Tool descriptions and registration
  • src/schemas/index.ts - Schema optimization logic
  • src/schemas/common.ts - (NEW) Shared schema patterns
  • src/core.ts - Environment configuration
  • src/server/handlers/*.ts - Response formatting optimization

Backwards Compatibility

  • All optimizations are opt-in via environment variables
  • Default behavior remains unchanged
  • Gradual rollout capability with feature flags
  • Comprehensive testing with existing clients

📈 Expected Outcomes

Quantitative Metrics

  • 57% reduction in initial context payload (29,450 chars saved)
  • Tool registration: 52KB → 22KB
  • Response payloads: 30-50% smaller (remove JSON pretty-printing)
  • Memory usage: Significant reduction in client memory footprint

Qualitative Benefits

  • ✅ Faster MCP connection establishment
  • ✅ Reduced token consumption in AI interactions
  • ✅ Better tool discovery through logical grouping
  • ✅ Improved developer experience
  • ✅ Foundation for future progressive loading features

🧪 Testing Requirements

Unit Tests

  • Test compact description generation
  • Test schema optimization logic
  • Test tool categorization filtering
  • Test backwards compatibility mode

Integration Tests

  • Test with Claude Code client
  • Test with custom MCP clients
  • Verify all 75 tools remain functional
  • Performance benchmarks (before/after)

Manual Testing

  • Test opt-in environment variables
  • Verify gradual rollout capability
  • Test category-based tool filtering
  • Validate memory usage reduction

📝 Documentation Updates

  • Update README with optimization options
  • Document environment variables in CLAUDE.md
  • Add performance tuning guide
  • Update API documentation with categories

⚠️ Risk Mitigation

Potential Risks

  1. Breaking changes for existing clients
  2. Performance regression from optimization logic
  3. Increased complexity in codebase

Mitigation Strategies

  • Opt-in approach ensures zero breaking changes
  • Performance testing before each phase
  • Clear separation of optimization logic
  • Comprehensive test coverage

🏷️ Labels

enhancement performance optimization memory client-experience

📊 Priority

High - Directly impacts all MCP client interactions and memory usage

🔗 Related Issues

  • Memory optimization discussions
  • Client performance improvements
  • Tool organization requests

✅ Definition of Done

  • All three phases implemented and tested
  • 57% reduction in context payload verified
  • Backwards compatibility maintained
  • Documentation updated
  • Performance benchmarks show improvement
  • No functional regressions
  • Code review approved
  • CI/CD pipeline passes

Success Criteria: Achieve 50%+ reduction in context overhead while maintaining 100% functionality and backwards compatibility.

Edited by John Haley