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:

Large Tool Schemas: Dashboard creation/update tools have deeply nested widget schemas (~5,000+ tokens each)
Preloaded Definitions: All 26 tools loaded at session start regardless of need
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

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

Next Steps

Immediate

✅ Restart Claude Code to apply changes
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:

Detects dashboard-related prompts
Temporarily removes deny patterns from .mcp.json
Prompts user to restart session
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

Dynamic access: Dashboard tools can be enabled when needed
Automatic cleanup: Deny patterns restored on session end via Stop hook
Clear patterns: Switched from regex to explicit deny patterns
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