Configuration

Filtering guide

Event Filtering & Control

Configure the Kilometers CLI to capture only the events you need with method whitelisting, risk-based filtering, and payload size controls.

Why Use Filtering?

Filtering helps you focus on relevant events, reduce bandwidth usage, and comply with data retention policies by capturing only what matters for your use case.

• Reduce Noise: Exclude routine operations like ping messages
• Focus on Security: Capture only high-risk operations
• Control Bandwidth: Limit payload sizes and method types
• Compliance: Monitor specific operations required by policy

Available Filtering Options

Method WhitelistingKM_METHOD_WHITELIST

Only capture specific MCP methods

Examples:

KM_METHOD_WHITELIST="tools/call"

Only monitor tool executions

KM_METHOD_WHITELIST="resources/read,resources/write"

Monitor file operations only

KM_METHOD_WHITELIST="tools/*"

All tool-related methods

KM_METHOD_WHITELIST="resources/*,prompts/get"

All resources + prompt access

Risk-Based FilteringKM_HIGH_RISK_ONLY

Filter events by security risk level

Examples:

KM_HIGH_RISK_ONLY="true"

Only capture high-risk events (75+ score)

KM_HIGH_RISK_ONLY="false"

Capture all events regardless of risk

Payload Size LimitsKM_PAYLOAD_SIZE_LIMIT

Exclude events with large payloads

Examples:

KM_PAYLOAD_SIZE_LIMIT="1024"

Skip events larger than 1KB

KM_PAYLOAD_SIZE_LIMIT="10240"

Skip events larger than 10KB

KM_PAYLOAD_SIZE_LIMIT="0"

No size limit (default)

Ping Message ExclusionKM_EXCLUDE_PING

Control ping message monitoring

Examples:

KM_EXCLUDE_PING="true"

Exclude ping messages (default)

KM_EXCLUDE_PING="false"

Include ping messages in monitoring

Method Pattern Matching

The method whitelist supports wildcards and multiple patterns for flexible filtering:

tools/callExact method match

tools/*All methods starting with 'tools/'

*callAll methods ending with 'call'

resources/read,tools/callMultiple specific methods

tools/*,resources/listPattern and specific method combined

Common Configuration Scenarios

Security-Focused Monitoring

Only capture high-risk operations for security analysis

Production environments where security is paramount

CONFIGURATION

KM_ENABLE_RISK_DETECTION=true
KM_HIGH_RISK_ONLY=true
KM_METHOD_WHITELIST="resources/read,tools/call"

Development Debugging

Capture all events except noisy ping messages

Local development and troubleshooting

CONFIGURATION

KM_EXCLUDE_PING=true
KM_DEBUG=true

Bandwidth-Conscious Setup

Minimize data transfer with size and method limits

Environments with limited bandwidth or storage

CONFIGURATION

KM_PAYLOAD_SIZE_LIMIT=5120
KM_METHOD_WHITELIST="tools/call,resources/write"
KM_EXCLUDE_PING=true

File Operations Only

Monitor only file system interactions

Tracking file access patterns and data movement

CONFIGURATION

KM_METHOD_WHITELIST="resources/read,resources/write,resources/list"
KM_PAYLOAD_SIZE_LIMIT=20480

Monitoring Filter Effectiveness

The CLI provides filtering statistics when events are processed:

[km] Filtering statistics:
[km] Total events: 1250
[km] Filtered events: 1100 (88.00%)
[km] Captured events: 150 (12.00%)
[km] Process completed successfully

This helps you understand how effective your filters are and tune them for optimal results.

Best Practices

Development Environment

• Use minimal filtering to see all activity
• Enable debug mode for visibility
• Exclude ping messages to reduce noise
• Test filters before deploying to production

Production Environment

• Use risk-based filtering for security focus
• Set payload limits to control data volume
• Whitelist specific methods for compliance
• Monitor filtering statistics regularly

Testing Your Filters

Test your filtering configuration with debug mode enabled to see what gets captured:

TEST COMMAND

KM_DEBUG=true KM_METHOD_WHITELIST="tools/call" KM_HIGH_RISK_ONLY=true km your-mcp-server

Risk Detection Environment Variables