query_live_capture_entries
Analyze live network traffic captures with structured filtering to inspect HTTP requests and responses. Filter by host, path, method, status, headers, or content to identify specific entries for debugging.
Instructions
Analyze the active live capture with structured summary-first filtering. This is the RECOMMENDED tool for inspecting live traffic. Does NOT advance the cursor — safe to call repeatedly with different filters. Default cursor=0 scans all captured data from the beginning. Use get_traffic_entry_detail to drill down into a specific entry_id.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| capture_id | Yes | ||
| cursor | No | ||
| preset | No | api_focus | |
| host_contains | No | ||
| path_contains | No | ||
| method_in | No | ||
| status_in | No | ||
| resource_class_in | No | ||
| min_priority_score | No | ||
| request_header_name | No | ||
| request_header_value_contains | No | ||
| response_header_name | No | ||
| response_header_value_contains | No | ||
| request_content_type | No | ||
| response_content_type | No | ||
| request_body_contains | No | ||
| response_body_contains | No | ||
| request_json_query | No | ||
| response_json_query | No | ||
| include_body_preview | No | ||
| max_items | No | ||
| max_preview_chars | No | ||
| max_headers_per_side | No | ||
| scan_limit | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| items | No | ||
| source | Yes | ||
| warnings | No | ||
| truncated | No | ||
| next_cursor | No | ||
| total_items | No | ||
| matched_count | No | ||
| scanned_count | No | ||
| filtered_out_count | No | ||
| filtered_out_by_class | No |
Implementation Reference
- charles_mcp/tools/live.py:140-201 (handler)The handler function for the `query_live_capture_entries` tool, which builds a traffic query and delegates analysis to the traffic_query_service.
async def query_live_capture_entries( ctx: ToolContext, capture_id: str, cursor: Optional[int] = None, preset: TrafficPreset = "api_focus", host_contains: Optional[str] = None, path_contains: Optional[str] = None, method_in: Optional[list[str]] = None, status_in: Optional[list[int]] = None, resource_class_in: Optional[list[str]] = None, min_priority_score: Optional[int] = None, request_header_name: Optional[str] = None, request_header_value_contains: Optional[str] = None, response_header_name: Optional[str] = None, response_header_value_contains: Optional[str] = None, request_content_type: Optional[str] = None, response_content_type: Optional[str] = None, request_body_contains: Optional[str] = None, response_body_contains: Optional[str] = None, request_json_query: Optional[str] = None, response_json_query: Optional[str] = None, include_body_preview: bool = True, max_items: int = 10, max_preview_chars: int = 128, max_headers_per_side: int = 6, scan_limit: int = 500, ) -> TrafficQueryResult: """Analyze the active live capture with structured summary-first filtering. This is the RECOMMENDED tool for inspecting live traffic. Does NOT advance the cursor — safe to call repeatedly with different filters. Default cursor=0 scans all captured data from the beginning. Use get_traffic_entry_detail to drill down into a specific entry_id.""" deps = get_tool_dependencies(ctx) query = build_traffic_query( preset=preset, host_contains=host_contains, path_contains=path_contains, method_in=method_in, status_in=status_in, resource_class_in=resource_class_in, min_priority_score=min_priority_score, request_header_name=request_header_name, request_header_value_contains=request_header_value_contains, response_header_name=response_header_name, response_header_value_contains=response_header_value_contains, request_content_type=request_content_type, response_content_type=response_content_type, request_body_contains=request_body_contains, response_body_contains=response_body_contains, request_json_query=request_json_query, response_json_query=response_json_query, include_body_preview=include_body_preview, max_items=max_items, max_preview_chars=max_preview_chars, max_headers_per_side=max_headers_per_side, scan_limit=scan_limit, ) return await deps.traffic_query_service.analyze_live_capture( capture_id=capture_id, query=query, cursor=cursor, ) - charles_mcp/tools/live.py:125-201 (registration)The tool is registered using the @mcp.tool() decorator within register_live_tools in charles_mcp/tools/live.py.
@mcp.tool() async def stop_live_capture( ctx: ToolContext, capture_id: str, persist: bool = True, ) -> StopLiveCaptureResult: """Stop an active live capture and optionally persist the filtered snapshot. Only status='stopped' means the capture is fully closed.""" deps = get_tool_dependencies(ctx) try: return await deps.live_service.stop(capture_id, persist=persist) except Exception as exc: raise ValueError(str(exc)) from exc @mcp.tool() async def query_live_capture_entries( ctx: ToolContext, capture_id: str, cursor: Optional[int] = None, preset: TrafficPreset = "api_focus", host_contains: Optional[str] = None, path_contains: Optional[str] = None, method_in: Optional[list[str]] = None, status_in: Optional[list[int]] = None, resource_class_in: Optional[list[str]] = None, min_priority_score: Optional[int] = None, request_header_name: Optional[str] = None, request_header_value_contains: Optional[str] = None, response_header_name: Optional[str] = None, response_header_value_contains: Optional[str] = None, request_content_type: Optional[str] = None, response_content_type: Optional[str] = None, request_body_contains: Optional[str] = None, response_body_contains: Optional[str] = None, request_json_query: Optional[str] = None, response_json_query: Optional[str] = None, include_body_preview: bool = True, max_items: int = 10, max_preview_chars: int = 128, max_headers_per_side: int = 6, scan_limit: int = 500, ) -> TrafficQueryResult: """Analyze the active live capture with structured summary-first filtering. This is the RECOMMENDED tool for inspecting live traffic. Does NOT advance the cursor — safe to call repeatedly with different filters. Default cursor=0 scans all captured data from the beginning. Use get_traffic_entry_detail to drill down into a specific entry_id.""" deps = get_tool_dependencies(ctx) query = build_traffic_query( preset=preset, host_contains=host_contains, path_contains=path_contains, method_in=method_in, status_in=status_in, resource_class_in=resource_class_in, min_priority_score=min_priority_score, request_header_name=request_header_name, request_header_value_contains=request_header_value_contains, response_header_name=response_header_name, response_header_value_contains=response_header_value_contains, request_content_type=request_content_type, response_content_type=response_content_type, request_body_contains=request_body_contains, response_body_contains=response_body_contains, request_json_query=request_json_query, response_json_query=response_json_query, include_body_preview=include_body_preview, max_items=max_items, max_preview_chars=max_preview_chars, max_headers_per_side=max_headers_per_side, scan_limit=scan_limit, ) return await deps.traffic_query_service.analyze_live_capture( capture_id=capture_id, query=query, cursor=cursor, )