SigNoz MCP Context Optimization: Implementing Tool Filtering and Search

Session Date: 2026-01-19
Project: Claude Code Configuration (~/.claude)
Focus: Minimize SigNoz MCP context/token usage in Claude Code
Session Type: Research and Implementation

Executive Summary

Successfully researched and implemented multiple strategies to reduce SigNoz MCP server context usage in Claude Code. The SigNoz MCP provides 26 tools consuming an estimated 15,000-20,000 tokens at session start. Through implementing mcp-filter proxy filtering and enabling aggressive tool search thresholds, achieved an estimated 85%+ reduction in context consumption.

The solution involved installing mcp-filter as a proxy wrapper around the SigNoz MCP server, blocking the three heaviest tools (signoz_create_dashboard, signoz_update_dashboard, signoz_execute_builder_query) which alone account for ~11,500 tokens. Combined with ENABLE_TOOL_SEARCH=auto:5, tools are now loaded on-demand rather than preloaded.

Key Metrics:

Metric Value
Total SigNoz Tools 27
Tools Blocked 25 (as of 2026-01-20)
Tools Retained 2 (list_services, search_metric_by_text)
Estimated Token Savings ~5,300 tokens (95%)
Tool Search Threshold 5% (aggressive)
Output Token Limit 25,000
Breaking Changes 0

Problem Statement

The SigNoz MCP server was contributing significant context overhead to Claude Code sessions:

  1. Large Tool Schemas: Dashboard creation/update tools have deeply nested widget schemas (~5,000+ tokens each)
  2. Preloaded Definitions: All 26 tools loaded at session start regardless of need
  3. Verbose Responses: MCP tool outputs could consume excessive context

Impact Before: ~20,000 tokens consumed by SigNoz MCP alone at session initialization.

Research Phase

Agent Selection Journey

Initially attempted to use lead-research-assistant agent, which didn’t exist in the available agents. After installing the skill from the awesome-claude-skills marketplace, discovered it was designed for sales lead generation, not technical research.

Resolution: Used webscraping-research-analyst agent for comprehensive technical research on MCP context optimization strategies.

Key Research Findings

1. MCP Tool Search (Built-in Solution)

  • Enabled by default as of January 2026
  • Dynamically loads tools on-demand via MCPSearch
  • Achieves 85% reduction when tools exceed threshold
  • Configurable threshold: ENABLE_TOOL_SEARCH=auto:N where N is percentage

2. Third-Party Proxy Tools

Tool Description Token Reduction
mcp-filter Python-based proxy with allow/deny patterns 72-91%
mcproxy Node.js proxy with auto-config generation Variable
Portkey filter Semantic embedding-based selection Variable

3. SigNoz Tool Analysis

Category Tools Schema Size
Metrics 4 Low (~150-200 tokens each)
Alerts 3 Low-Medium
Dashboards 4 Very High (~5,000+ for create/update)
Services 2 Medium
Logs 7 Low-Medium
Traces 6 Medium-High
Query Builder 1 High (~1,500 tokens)

4. Feature Request Status

  • Native tool filtering (Issue #7328) has 182+ upvotes, assigned but not yet implemented
  • Proxy-based filtering is the current community workaround

Implementation Details

Phase 1: Install mcp-filter

Command:

pip install mcp-filter

Installed Dependencies: mcp-filter 0.1.0 with fastmcp, mcp, and related packages.

Phase 2: Update MCP Configuration

File: ~/.claude/.mcp.json

Before:

{
  "mcpServers": {
    "signoz": {
      "command": "/Users/alyshialedlie/.claude/mcp-servers/signoz-mcp-server/bin/signoz-mcp-server",
      "args": [],
      "env": {
        "SIGNOZ_URL": "https://tight-ladybird.us.signoz.cloud",
        "SIGNOZ_API_KEY": "${SIGNOZ_API_KEY}",
        "LOG_LEVEL": "info",
        "GOMEMLIMIT": "50MiB",
        "GOGC": "50"
      }
    }
  }
}

After:

{
  "mcpServers": {
    "signoz": {
      "command": "mcp-filter",
      "args": [
        "run",
        "-t", "stdio",
        "--stdio-command", "/Users/alyshialedlie/.claude/mcp-servers/signoz-mcp-server/bin/signoz-mcp-server",
        "--deny-pattern", "signoz_(create|update)_dashboard",
        "--deny-pattern", "signoz_execute_builder_query",
        "--log-level", "WARNING"
      ],
      "env": {
        "SIGNOZ_URL": "https://tight-ladybird.us.signoz.cloud",
        "SIGNOZ_API_KEY": "${SIGNOZ_API_KEY}",
        "LOG_LEVEL": "info",
        "GOMEMLIMIT": "50MiB",
        "GOGC": "50"
      }
    }
  }
}

Design Decisions:

  • Deny patterns over allow lists: More maintainable as new tools are added
  • Regex patterns: signoz_(create|update)_dashboard catches both in one pattern
  • Log level WARNING: Reduces noise while preserving important messages

Phase 3: Enable Tool Search and Output Limits

File: ~/.claude/config/settings.json

Added Configuration:

{
  "env": {
    "ENABLE_TOOL_SEARCH": "auto:5",
    "MAX_MCP_OUTPUT_TOKENS": "15000"
  }
}

Rationale:

  • auto:5: Triggers tool search when MCP tools exceed 5% of context (more aggressive than default 10%)
  • MAX_MCP_OUTPUT_TOKENS=15000: Prevents verbose tool responses from consuming excessive context

Phase 4: Cleanup

  • Disabled lead-research-assistant@awesome-claude-skills plugin
  • Removed skill from skill-rules.json
  • Deleted skill folder from ~/.claude/skills/

Key Decisions and Trade-offs

Decision 1: mcp-filter vs mcproxy

Choice: mcp-filter (Python-based) Rationale: Simpler CLI interface, regex-based patterns, well-documented Alternative Considered: mcproxy (Node.js), rejected due to additional config file requirement Trade-off: Python dependency vs Node.js dependency (Python already available)

Decision 2: Deny Patterns vs Allow List

Choice: Deny patterns blocking 3 heavy tools Rationale: Future-proof as new SigNoz tools are added; only blocks known heavy tools Alternative Considered: Allow list of ~10 essential tools Trade-off: Less aggressive filtering, but more maintainable

Decision 3: Tool Search Threshold

Choice: 5% threshold (aggressive) Rationale: Maximizes context savings; SigNoz tools alone likely exceed 5% Alternative Considered: Default 10% Trade-off: Slightly slower tool discovery for maximum context savings

Tools Blocked

Tool Estimated Tokens Reason
signoz_create_dashboard ~5,000+ Deeply nested widget/query schemas
signoz_update_dashboard ~5,000+ Same as create
signoz_execute_builder_query ~1,500 Complex query structure
Total Blocked ~11,500  

Tools Retained (23)

All other SigNoz tools remain available:

  • signoz_list_services, signoz_list_alerts, signoz_get_alert
  • signoz_get_error_logs, signoz_search_logs_by_service
  • signoz_search_traces_by_service, signoz_get_trace_details
  • signoz_list_dashboards, signoz_get_dashboard
  • And 14 more utility/query tools

Verification

Configuration Validation

$ npm run validate
✓ skill-rules.json is valid JSON
✓ All 21 skills have matching SKILL.md files and triggers
✓ settings.json is valid JSON
✓ All checks passed!

JSON Validation

$ cat .mcp.json | python3 -c "import json,sys; json.load(sys.stdin)"
✓ .mcp.json is valid JSON

Files Modified

Modified Files

File Changes
~/.claude/.mcp.json Added mcp-filter wrapper with deny patterns
~/.claude/config/settings.json Added env settings, disabled plugin
~/.claude/config/skill-rules.json Removed lead-research-assistant

Deleted Files

File Reason
~/.claude/skills/lead-research-assistant/ Not needed for technical research

Note on .mcp.json

The .mcp.json file is gitignored and changes remain local-only. This is appropriate as the file may contain environment-specific paths.

Git Commits

Commit Description
22b1db4 perf(mcp): add tool search and output limits for context optimization

Expected Performance Impact

Scenario Before After Improvement
Initial Context Load ~20,000 tokens ~3,000-5,000 tokens 75-85%
With Tool Search Active ~20,000 tokens ~500 tokens 97%+
Dashboard Operations Available Blocked N/A

Limitations

  1. Dashboard Creation Blocked: Cannot create/update dashboards via MCP (must use SigNoz UI) Resolved: Dynamic dashboard mode hooks added (2026-01-20)
  2. Query Builder Blocked: Complex queries must use specific tools or UI
  3. Native Filtering Unavailable: Still waiting on Claude Code Issue #7328 for built-in solution

Next Steps

Immediate

  1. ✅ Restart Claude Code to apply changes
  2. Use /context command to verify token reduction

If Dashboard Access Needed

  • Temporarily modify .mcp.json to remove deny patterns Automated via hooks (2026-01-20)
  • Use prompt like “create a signoz dashboard” to trigger dashboard mode
  • Or use SigNoz web UI directly

Future Improvements

  • Monitor Issue #7328 for native tool filtering
  • Consider creating SigNoz guidance skill for tool selection

Follow-up Session: 2026-01-20

Dynamic Dashboard Mode Hooks

Added hooks to temporarily enable/disable dashboard tools on-demand, solving the “dashboard access blocked” limitation.

Problem: Dashboard tools are denied for context savings, but occasionally needed for dashboard work.

Solution: Created hook-based workflow that:

  1. Detects dashboard-related prompts
  2. Temporarily removes deny patterns from .mcp.json
  3. Prompts user to restart session
  4. Automatically restores deny patterns when session ends

Files Created/Modified

File Purpose
hooks/handlers/signoz-dashboard-mode.ts Core enable/disable logic
hooks/handlers/user-prompt.ts Detects dashboard intent, enables mode
hooks/handlers/stop.ts Restores deny patterns on session end

Updated MCP Configuration

Changed from regex patterns to explicit deny patterns for clarity:

{
  "args": [
    "run",
    "-t", "stdio",
    "--stdio-command", "/path/to/signoz-mcp-wrapper",
    "--deny-pattern", "signoz_execute_builder_query",
    "--deny-pattern", "signoz_create_dashboard",
    "--deny-pattern", "signoz_update_dashboard",
    "--log-level", "WARNING"
  ]
}

Dashboard Mode Detection Patterns

The hook detects prompts matching:

  • create (a) signoz dashboard
  • update (a) signoz dashboard
  • build/make/new signoz dashboard
  • signoz dashboard mode
  • enable dashboard (tools|mode)

Usage Flow

User: "create a signoz dashboard for API metrics"
Hook: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
      🔧 SIGNOZ DASHBOARD MODE
      Dashboard tools enabled.
      ⚠️  RESTART REQUIRED
      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

User: /clear (restarts session)
[Dashboard tools now available]
[... dashboard work ...]
[Session ends]

Hook: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
      🔒 SIGNOZ DASHBOARD MODE DISABLED
      Deny patterns restored for next session.
      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Context Usage by Tool Category

Estimated token consumption for enabled SigNoz tools:

Category Est. Tokens Tools
High 2,000-4,000 update_dashboard (now denied)
Medium 500-1,000 search_traces, search_logs, get_trace_*
Low 200-400 list_*, get_*, search_metric_*

Denied Tools Summary

Tool Est. Tokens Status
signoz_execute_builder_query ~1,500 Denied
signoz_create_dashboard ~4,000 Denied (dynamic enable available)
signoz_update_dashboard ~4,000 Denied (dynamic enable available)
Total Savings ~9,500  

Key Improvements

  1. Dynamic access: Dashboard tools can be enabled when needed
  2. Automatic cleanup: Deny patterns restored on session end via Stop hook
  3. Clear patterns: Switched from regex to explicit deny patterns
  4. Observability: All hook operations instrumented with OpenTelemetry

Follow-up Session: 2026-01-20 (Aggressive Tool Filtering)

Minimal Tool Set for Metrics-Only Workflow

Expanded deny patterns to block nearly all SigNoz query tools, keeping only 2 tools needed for verification.

Rationale: Metrics ingestion is handled by OpenTelemetry exporters in the hooks system, not by MCP query tools. The MCP tools are read-only for querying data from SigNoz.

Updated MCP Configuration

{
  "args": [
    "run",
    "-t", "stdio",
    "--stdio-command", "/path/to/signoz-mcp-wrapper",
    "--deny-pattern", "signoz_execute_builder_query",
    "--deny-pattern", "signoz_create_dashboard",
    "--deny-pattern", "signoz_update_dashboard",
    "--deny-pattern", "signoz_get_alert",
    "--deny-pattern", "signoz_get_alert_history",
    "--deny-pattern", "signoz_get_dashboard",
    "--deny-pattern", "signoz_get_error_logs",
    "--deny-pattern", "signoz_get_log_view",
    "--deny-pattern", "signoz_get_logs_available_fields",
    "--deny-pattern", "signoz_get_logs_field_values",
    "--deny-pattern", "signoz_get_logs_for_alert",
    "--deny-pattern", "signoz_get_metrics_available_fields",
    "--deny-pattern", "signoz_get_metrics_field_values",
    "--deny-pattern", "signoz_get_service_top_operations",
    "--deny-pattern", "signoz_get_trace_available_fields",
    "--deny-pattern", "signoz_get_trace_details",
    "--deny-pattern", "signoz_get_trace_error_analysis",
    "--deny-pattern", "signoz_get_trace_field_values",
    "--deny-pattern", "signoz_get_trace_span_hierarchy",
    "--deny-pattern", "signoz_list_alerts",
    "--deny-pattern", "signoz_list_dashboards",
    "--deny-pattern", "signoz_list_log_views",
    "--deny-pattern", "signoz_list_metric_keys",
    "--deny-pattern", "signoz_search_logs_by_service",
    "--deny-pattern", "signoz_search_traces_by_service",
    "--log-level", "WARNING"
  ]
}

Tools Retained (2 of 27)

Tool Purpose
signoz_list_services Verify services are reporting to SigNoz
signoz_search_metric_by_text Spot-check specific metrics

Token Savings

Metric Before After Savings
Tools Loaded 27 2 25 tools
Context Usage ~5,600 tokens ~300 tokens ~5,300 tokens (95%)

Key Insight

The SigNoz MCP server provides query/read capabilities, not ingestion. Metrics, traces, and logs are ingested via OTEL exporters configured in the hooks:

OpenTelemetry: Traces exporting to https://ingest.us.signoz.cloud/v1/traces
OpenTelemetry: Metrics exporting to https://ingest.us.signoz.cloud/v1/metrics
OpenTelemetry: Logs exporting to https://ingest.us.signoz.cloud/v1/logs

All 27 MCP tools can be safely disabled without affecting telemetry ingestion.

References

Code Files

  • ~/.claude/.mcp.json - MCP server configuration
  • ~/.claude/config/settings.json - Claude Code settings
  • ~/.claude/config/skill-rules.json - Skill triggers
  • ~/.claude/hooks/handlers/signoz-dashboard-mode.ts - Dashboard mode enable/disable logic
  • ~/.claude/hooks/handlers/user-prompt.ts - Dashboard intent detection
  • ~/.claude/hooks/handlers/stop.ts - Session cleanup and deny pattern restoration

External Resources

Research Agents Used

  • general-purpose - Initial MCP configuration research
  • webscraping-research-analyst - Comprehensive optimization strategy research