wlanpi-mcp

Official

Overview Schema Source Related Servers Discussions Admin

start_pcap_file

Starts a non-streaming packet capture on an interface, saves raw pcapng data to a managed file, and returns immediately with a capture ID and path for later retrieval.

Instructions

Start a background, non-streaming packet capture to a pcapng file.

This is the non-streaming counterpart to capture_scan: unlike that streaming tool, it does not block and does not return a dissected summary. It starts a capture, keeps the core WebSocket open in the background, and writes the raw pcapng bytes to a file under a managed directory on the device. Because nothing is held in memory or returned inline, the capture can run far longer than the 60 s capture_scan window — up to the server's configured maximum. The call returns immediately with the capture_id and file path; the capture then runs on its own until duration_s elapses or you call stop_pcap_file. Retrieve the file with fetch_pcap_file(capture_id=...) (a pcapng blob) once it has stopped.

This tool always owns the interface. If a capture is already running on it, this returns an error rather than taking it over — watch that one with capture_observe instead.

Args: interface: Monitor-mode capture interface, always 'wlanpiN' (e.g. 'wlanpi0'), not 'wlan0'. See get_capture_channels. channels: Channel numbers to hop (e.g. [1, 6, 11, 36]); 6 GHz can be given as explicit frequencies in MHz. Omit to hop every channel the adapter supports. width: Channel width in MHz: 20, 40, 80 or 160. dwell_ms: Milliseconds to dwell on each channel (50-60000). duration_s: How long the background capture runs, in seconds, from 1 up to the server maximum (default max 3600). The call itself returns immediately. pcap_filter: Optional BPF/pcap filter, e.g. 'type mgt subtype beacon'.

Input Schema

TableJSON Schema

Name	Required	Default
`width`	No
`channels`	No
`dwell_ms`	No
`interface`	No	wlanpi0
`duration_s`	No
`pcap_filter`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 20, 2026

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and fully meets it. It discloses that the call returns immediately, the capture runs in the background until duration_s or stop_pcap_file, the WebSocket remains open, and the tool 'always owns the interface' and returns an error if a capture is already running. This is unusually complete behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The text is long but every paragraph earns its place: first the core behavior, then the lifecycle and retrieval path, then ownership semantics, then parameter detail. The most important distinction from capture_scan is front-loaded in the opening sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has six parameters, no annotations, and multiple interacting siblings; the description covers the full lifecycle, ownership constraints, error behavior, and parameter semantics. Since an output schema exists, the absence of exhaustive return-field detail is acceptable: the description already mentions capture_id and file path.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description's Args section documents every parameter with concrete guidance: interface must be 'wlanpiN' not 'wlan0', channels can include 6 GHz frequencies, dwell_ms ranges 50-60000, duration_s goes up to the server maximum, and pcap_filter gets a real BPF example. This adds meaning far beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Start a background, non-streaming packet capture to a pcapng file.' It clearly differentiates itself from capture_scan by stating it is the 'non-streaming counterpart' that does not block or return a dissected summary. This lets an agent unambiguously pick it over its siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly explains when to use this tool versus capture_scan: for long captures beyond the 60-second window, and when an inline summary is not needed. It also names the alternatives for supervising and retrieving results (capture_observe, stop_pcap_file, fetch_pcap_file) and states the failure mode when a capture is already running on the interface.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server