Scanner MCP Tools Reference
Scanner provides three core MCP tools that enable AI agents and interactive clients to query security data, explore your environment, and execute threat hunting operations.
Overview
get_scanner_context
Load Scanner query documentation, available indexes, and source types
Loaded first by AI agents
execute_query
Run ad-hoc queries against Scanner logs
Core query execution
fetch_query_results
Retrieve specific fields from cached query results
Result refinement
Design: Efficient Context Management
Scanner MCP tools are designed to work together efficiently, avoiding context bloat that would consume excessive tokens and reduce AI agent capability.
The Challenge: Security queries often return thousands of rows. Loading all raw results into the AI's context would:
Consume massive amounts of tokens
Reduce the AI's ability to reason about findings
Make investigations slower and more expensive
The Solution: A two-stage result retrieval pattern:
execute_query returns a summary of results, not raw data:
Field names and top values for each field
Row count and data patterns
Statistical summaries (counts, distributions, time ranges)
A
result_handlefor later access
fetch_query_results allows selective retrieval:
AI examines the summary from execute_query
AI decides which fields and rows are actually relevant
Uses fetch_query_results to pull only those specific fields/rows into context
Avoids loading irrelevant data
Example: Query returns 5,000 S3 access events. Rather than load all 5,000 rows with all fields (massive context), the AI:
Sees the summary showing event types, usernames, buckets involved
Identifies which 50 rows are suspicious
Fetches only those 50 rows with only relevant fields (
eventTime,userName,bucketName)Saves 90% of token usage while retaining key context
This design enables AI agents to handle large datasets without context limitations becoming a bottleneck.
1. get_scanner_context
Purpose: Load complete Scanner context including query documentation, available indexes, source types, and field statistics.
Key Points:
Loads context first — AI agents are instructed to call this before executing any queries
Returns a context_token — Required input for
execute_queryDiscovers your data — Shows what indexes and source types are available in your Scanner instance
Documentation included — Returns complete query syntax reference and examples
What It Provides:
Scanner query language syntax and operators
Available built-in indexes (e.g.,
_detections,_audit)Discovered source types (e.g.,
aws:cloudtrail,kubernetes:audit,proxy,dns)Field statistics showing most common fields across your data
Query syntax validation rules
Example queries for common use cases
When to Use:
Start of any investigation or query session
When exploring a new data source
To understand available fields before writing queries
To validate query syntax rules
Example Usage:
1. Call get_scanner_context (no parameters needed)
2. Receive context_token and documentation
3. Use context_token with execute_query2. execute_query
Purpose: Execute an ad-hoc query against Scanner to search your security logs.
Required Parameters:
context_token — Obtained from
get_scanner_context(proves you've loaded syntax rules)query — Your Scanner Query Language query
start_time — Query start time (ISO 8601 format, inclusive)
end_time — Query end time (ISO 8601 format, exclusive)
Optional Parameters:
max_rows — Maximum rows to return (default: 1000, max: 10000)
max_bytes — Memory limit in bytes (default: 128MB)
Key Features:
Blocking execution — Waits for results (supports configurable timeouts)
Result caching — Results are cached for subsequent operations
Field-level summaries — Returns summaries to reduce token usage
Time-bounded queries — Scope queries to specific time windows
What It Returns:
Query execution status
Result summary with key findings
A
result_handlefor fetching detailed results withfetch_query_resultsRow count and execution time
Sample of returned fields
When to Use:
Execute threat hunting queries
Search for specific events or patterns
Investigate alerts or incidents
Test detection rule logic
Explore data patterns
Example Usage:
execute_query with:
- context_token: [from get_scanner_context]
- query: %ingest.source_type="aws:cloudtrail" eventName=DeleteTrail
- start_time: 2025-11-18T00:00:00Z
- end_time: 2025-11-19T00:00:00Z
- max_rows: 100
Returns: Summary of matching CloudTrail events with a result_handle for detailed retrieval3. fetch_query_results
Purpose: Retrieve specific fields and rows from previously executed query results.
Required Parameters:
result_handle — Cache handle returned from
execute_queryfields — List of field names to retrieve (required)
Optional Parameters:
limit — Maximum matching rows to return (default: 50, max: 1000)
offset — Rows to skip before filtering (default: 0)
row_filter_regex — Regex pattern to filter which rows are returned
Key Features:
Selective field retrieval — Fetch only the fields you need
Pattern matching — Filter results with regex to find specific events
Pagination support — Use offset and limit for large result sets
Efficient browsing — Avoids re-executing queries
When to Use:
Get detailed results after an initial query
Extract specific fields from large result sets
Filter results to find matching events
Drill down into query results progressively
Refine investigation based on initial findings
Example Usage:
After execute_query returns a result_handle:
fetch_query_results with:
- result_handle: [from execute_query]
- fields: [userIdentity.userName, eventName, sourceIPAddress, eventTime]
- limit: 50
- row_filter_regex: "admin.*"
Returns: 50 rows of matching events showing only the specified fields where username matches regexRelated Documentation
Getting Started — Setup instructions for Scanner MCP in different tools
Detection Engineering — Use Scanner MCP to build and validate detection rules
Autonomous Workflows — Build agents using Scanner MCP tools
Interactive Investigations — Run investigations with Scanner MCP
Last updated
Was this helpful?