MCP Tools Server - NormB/sipnab GitHub Wiki
The server bundle reports on the sipnab process and its capture path:
capture health, HEP senders, resource use and build capabilities, and it stops
the server.
Load only these tools with --mcp-tools server, or combine bundles as
Choosing which tools load describes.
Every tool on this page follows the rules every tool
follows, and each section states only
what its tool does differently. The MCP tool reference lists
the other bundles and finds any tool by name.
| Tool | Parameters | Returns |
|---|---|---|
runtime_stats |
sample_seconds? |
What sipnab is doing and what it costs the host: its own memory, threads, descriptors and CPU; the host's totals and the basis they came from; its share of them and whether that share is load-bearing; per-interface counters; store occupancy against the caps |
capture_health |
sample_seconds |
Capture-path counters read twice: run totals, deltas across the window, undecoded_fraction, and undecodable frames by reason |
fleet_inventory |
-- | What this process is, for a fleet controller: build, binary SHA-256, signature state, configuration digests, privilege, uptime, interface, capture and HEP counters, and HEP sender addresses |
hep_senders |
limit? |
Who feeds this run's HEP listener: each sender, its count, when it was last heard and whether it went silent, and every address the listener refused, by reason |
server_capabilities |
-- | sipnab version, the optional features this binary carries, and the libpcap it runs |
shutdown_server |
dry_run?, save_to?, discard_unsaved? |
Destructive. Stops the process. Needs --mcp-allow-shutdown; dry-run by default |
Survey — what is in this capture
Start here when you have a capture and no particular suspect. These answer "what is in it", "how much", and "is the server even seeing traffic".
runtime_stats
What sipnab is doing, and what it is costing the host it runs on.
Use it to answer "is this server healthy" without a metrics listener. sipnab exports 51 Prometheus metrics, and the listener that serves them is off by default. This tool reports process, host and store state over MCP without that listener.
Starts no capture. Every field below answers at once. The one optional
parameter, sample_seconds, adds rates and makes the call wait that long.
Parameters: sample_seconds? (u32, optional) — 1 to 30. sipnab clamps a
larger value to 30, and rates.window_seconds reports the window applied. 0
fails with invalid_params. Omitted, the response has no rates block and
the call does not wait.
The example runs against
tests/pcap-samples/sip-rtp-g711.pcap:
// runtime_stats {}
{
"schema_version": 1,
"process": {
"rss_bytes": 23654400, "virtual_bytes": 1258172416,
"threads": 3, "open_fds": 10, "cpu_seconds": 0.01
},
"host": {
"memory_total_bytes": 131881897984,
"memory_available_bytes": 55933124608,
"cpus": 14, "basis": "host"
},
"impact": {
"memory_pct": 0.01793604760136965, "significant": false,
"note": "sipnab holds 0.0% of the host memory total; the threshold for load-bearing is 10.0%"
},
"interfaces": [],
"dialogs": { "used": 2, "capacity": 100000, "pct": 0.002 },
"streams": { "used": 2, "capacity": 50000, "pct": 0.004 },
"capture_sources": { "used": 1, "capacity": 65536, "pct": 0.00152587890625 },
"capture_sources_refused_total": 0,
"capture_packets_total": 852,
"capture_queue_depth_packets": 0,
"capture_backpressure_blocks_total": 0,
"uptime_seconds": 0,
"capture_identity": {
"node": "capture-01", "instance": "12e28118df11310000ef0c-2",
"dialog_generation": 13, "stream_generation": 2
},
"source_exhausted": true,
"source_stopped_early": false
}
A --hep-send run also carries hep_export: the transport, packets_sent,
failures by kind (connect, tls_handshake, write, every kind present),
reconnects, queued, replayed after an outage, dropped by reason
(queue_full, stopped, unsent_at_exit, every reason present),
queue_depth, and delivery, which says what "sent" means on that transport.
Over UDP it means handed to the kernel: a collector that is down produces no
failure. The shape is the same as GET /v1/runtime's, from the same collector.
How to read it:
- An absent field means "not readable here", never zero. Every value
under
processandhostis optional, because the sources are platform-specific. host.basisnames the denominator. Inside a container the basis readscgroupand the totals come from the control group'smemory.max, not the machine's memory.impact.significant: truemeans sipnab's own memory use is load-bearing on this host, at or above the thresholdnotestates (10% of the host memory total).interfacesreads the network interface, not the capture handle. Compare the two to choose a remedy:ps_ifdropclimbing withrx_missed_errorsmeans the NIC cannot keep up (adjust ring size, coalescing or RSS);ps_dropclimbing alone means sipnab's read loop is falling behind (raise--bufferor tighten the capture filter).- The capture-queue fields are absent without a capture meter. A run
replaying a file through the API omits
capture_queue_depth_packetsandcapture_backpressure_blocks_total, rather than reporting0. - Read occupancy against capacity.
dialogs.pctandstreams.pctnear 100 mean the store is about to evict calls. capture_identitynames the capturedialogs.usedandstreams.usedcount. It is the identitycapture_statusreports, read at the same moment as the occupancy.
To get rates, pass sample_seconds. Every counter above is cumulative.
With sample_seconds, sipnab reads the counters twice across that window and
adds a rates member to the same envelope, with calls broken down by method
so that OPTIONS keepalives and INVITEs appear apart. Every other member is as
above. The rates member alone:
// runtime_stats { "sample_seconds": 2 }, the value of "rates"
{
"window_seconds": 2,
"packets_per_second": 0.0,
"calls_per_second": 0.0,
"calls_per_second_by_method": ["INVITE", 0.0](/NormB/sipnab/wiki/"INVITE",-0.0)
}
The rates in that example are zero because the file had finished loading before the window opened. On a live capture they carry the traffic seen during the window.
window_seconds is the window sipnab applied: sipnab clamps a longer
request to 30 seconds. sample_seconds: 0 fails with invalid_params:
sample_seconds must be at least 1. A zero-second window observes nothing, and a response of zero deltas reads as a quiet capture.
The REST endpoint GET /v1/runtime returns the same envelope, with the same
refusal and the same 30-second cap.
capture_health
Reads the capture counters, waits, and reads them again. The response carries the run totals and the change across that window, which turns a pile of monotonic counters into a rate.
You must pass sample_seconds: this tool has no default window. The call
blocks for that long.
Use capture_status for what the counters
say right now, and capture_health for what they did over a window you chose:
whether the process is dropping packets now, not only since it started.
Three questions it answers on a busy production server:
- Does the capture path drop packets under load? Read
in_window.kernel_droppedandin_window.interface_dropped. They are reported separately because their fixes differ: a bigger ring buffer (--buffer) cures the first and does nothing for the second. - What is on this wire that sipnab cannot decode? Read
undecodable_by_reason. Each entry names the reason as a code and carries the number that identifies it: the link type, the EtherType, or the IP protocol. - What does the encapsulation-aware capture filter cost? Run the same
window twice, once with
--capture-tunnelsand once without, and comparein_window.packetsagainst the two drop counters.
| Name | Type | Legal values | If omitted |
|---|---|---|---|
sample_seconds |
u32 | 1 to 30. A larger value clamps to 30, and window.requested_seconds beside window.applied_seconds reports both. Zero fails with sample_seconds must be at least 1. |
Required — the call fails with missing field \sample_seconds``. |
The call blocks for the whole window, so a client with a short request timeout should ask for a few seconds rather than 30.
The example runs against
tests/pcap-samples/SIP_CALL_RTP_G711,
a capture file, so the totals hold the whole file and the window is empty:
// capture_health { "sample_seconds": 2 }
{
"schema_version": 1,
"attachment": 3,
"window": {
"requested_seconds": 2,
"applied_seconds": 2,
"observed_ms": 2001
},
"totals": {
"packets": 4269,
"kernel_dropped": 0,
"interface_dropped": 0,
"invalid_timestamps": 0,
"undecodable_frames": 164
},
"in_window": {
"packets": 0,
"kernel_dropped": 0,
"interface_dropped": 0,
"invalid_timestamps": 0,
"undecodable_frames": 0
},
"undecoded_fraction": 0.038416490981494494,
"undecoded_fraction_in_window": 0.0,
"undecodable_by_reason": [
{ "reason": 2, "number": null, "frames": 164, "frames_in_window": 0 }
],
"undecodable_reasons_dropped": 0,
"dialogs_tracked": 4,
"streams_tracked": 5,
"clock": {
"synchronized": true,
"max_error_us": 918000,
"est_error_us": 0,
"available": true
},
"capture_sources": { "held": 1, "limit": 65536, "refused": 0 },
"source_exhausted": true,
"source_stopped_early": false
}
Every response carries capture_sources: how many capture sources the source
table holds, its limit ([limits] max_capture_sources), and packets from a new
source it refused because it was full. Counts only, never the names.
On a run with a HEP listener (-L), the response also carries hep: the
listener's counts, and nothing else.
"hep": {
"senders_tracked": 1, "senders_silent": 0, "packets_received": 33,
"packets_admitted": 10, "packets_refused": 23, "untracked_packets": 0
}
Integers only, like the rest of the response. For which senders, their
addresses and the ids they claim, ask hep_senders. Without
a listener the hep key is absent.
To check whether the whole capture arrived, read source_stopped_early.
It is true when a file's read ended before the file did: libpcap error: truncated dump file, a file that would not open, or a read that hit an error
part-way through. The newest file of a ring buffer that sipnab or another
program is still writing commonly reads this way.
This tool starts no capture. With
--mcpattached to a live interface, the counters already accumulate, so a rate costs two reads and a wait. The handler opens no device, names no interface, and writes no file.
No value in this response is a string. The response holds integers, codes, two proportions and the clock's booleans, so it carries no packet content. The reasons travel as codes, and their meanings are in the tables below.
attachment — what this server has packets from
| Code | Meaning |
|---|---|
1 |
Nothing attached. No capture context reached this server. |
2 |
A live interface. |
3 |
A capture file replaying. |
With code 1, every counter is zero because there is nothing to count, not
because the wire is quiet. No code is 0.
undecodable_by_reason — the reason codes
reason |
Meaning | What number carries |
Where to start |
|---|---|---|---|
1 |
The pcap link type has no decoder here | The DLT number | editcap -T ether converts a DLT_NULL (0) or DLT_LINUX_SLL (113) file |
2 |
The link layer named a payload that is not IP | The EtherType, or null when the link layer records none |
34887 is 0x8847, so the mirror carries MPLS. 2054 is ARP, which every Ethernet capture carries and nothing needs to decode |
3 |
An IP header decoded, and its payload is no transport sipnab handles | The outermost IP protocol, or null when the decoder recorded none |
47 is GRE and 4/41 are IP-in-IP. --capture-tunnels widens the filter to reach inside them |
4 |
The frame is shorter than a header it claims | null |
Raise --snaplen. A cut frame is a capture setting, not a parser gap |
5 |
A decoder rejected the bytes | null |
Save a sample and open an issue |
Use number to find the action: reason 1 with number 0 means a
DLT_NULL file to convert, where reason 1 alone would not say which. In the
example above, reason 2 with number: null means the link layer named a
non-IP payload and recorded no EtherType. frames counts the whole run and
frames_in_window the sample. An entry whose frames_in_window is 0
describes a problem that has already stopped.
undecodable_reasons_dropped counts frames whose specific number did not fit
the per-reason tables behind these counters. When it is non-zero, the
breakdown adds up to less than totals.undecodable_frames.
Choose a sampling window
sipnab caps the window at 30 seconds, because the call blocks the agent that
made it for the whole window, and many MCP clients cancel a call that has not
answered within 60 seconds. At 10,000 packets per second, 30 seconds samples
300,000 packets. For a longer view, call the tool repeatedly and read
totals.
To compute a rate, divide by window.observed_ms, not by sample_seconds:
the handler can wake late on a loaded host, and observed_ms is the measured
wall-clock window.
Check the clock before matching calls across servers
The clock object (synchronized, max_error_us, est_error_us,
available) comes from adjtimex(2) at report time, so it reflects a host
that lost its time source after sipnab started.
Within one capture the clock does not matter: one clock stamped every packet.
It matters when you correlate calls across servers.
find_correlated's
timing_heuristic matches dialogs that started within the leg-correlation
window of each other, two seconds unless --leg-correlation-window says
otherwise. A clock three seconds fast fails to correlate legs that belong
together, and a slow one pulls unrelated legs inside the window. Widening the
window widens this exposure.
Before trusting a time-based match across servers, read clock from both, and
prefer a leg matched by any strategy other than timing_heuristic. Every other
strategy compares an identifier, so it does not depend on the clock.
available: false means the platform gave no answer. It does not mean the
clock lost synchronization.
hep_senders
Who is feeding this run's HEP listener, who went silent, and who it is turning
away. Exists in a build with the hep feature. Starts nothing and waits for
nothing: it reads the roster the listener keeps.
The example comes from one host: a listener started with
sipnab --mcp -N -L 127.0.0.1:8070 --hep-auth s3cret, one sender started with
sipnab -N -I tests/pcap-samples/sip-rtp-g711.pcap -H 127.0.0.1:8070 --hep-id 7 --hep-auth s3cret,
and a second sender with the wrong secret (--hep-id 9 --hep-auth wrong).
Both senders share the address 127.0.0.1:
// hep_senders {}
{
"listening": true,
"packets_admitted": 10,
"packets_received": 20,
"packets_refused": 10,
"refused_by_reason": {
"allowlist": 0,
"auth_mismatch": 10,
"auth_missing": 0,
"event_sender_not_listed": 0,
"hmac_bad_format": 0,
"hmac_bad_mac": 0,
"hmac_replay": 0,
"hmac_timestamp_out_of_window": 0,
"hmac_unsupported_version": 0,
"malformed": 0,
"peer_tracking_full": 0,
"rate_limit_global": 0,
"rate_limit_per_peer": 0
},
"refused_sources": [
{
"by_reason": {
"auth_mismatch": 10
},
"first_seen": "2026-10-18T15:29:53.069Z",
"last_seen": "2026-10-18T15:29:53.138Z",
"packets": 10,
"peer": "127.0.0.1"
}
],
"refused_sources_evicted": 0,
"refused_sources_limit": 256,
"refused_sources_tracked": 1,
"schema_version": 1,
"senders": [
{
"capture_id": 7,
"first_seen": "2026-10-18T15:29:52.818Z",
"identity": "claimed_by_sender",
"idle_seconds": 2,
"last_seen": "2026-10-18T15:29:52.830Z",
"packets": 10,
"peer": "127.0.0.1",
"silent": false,
"source": "hep:[email protected]",
"trust": "shared_secret_plain"
}
],
"senders_limit": 4096,
"senders_silent": 0,
"senders_tracked": 1,
"silence_threshold_seconds": 30,
"source_exhausted": false,
"source_stopped_early": false,
"trust": "shared_secret_plain",
"untracked_packets": 0
}
refused_by_reason carries all twelve reasons, zeros included.
| Name | Type | Legal values | If omitted |
|---|---|---|---|
limit? |
u32? | The most rows senders and refused_sources each carry, up to the server's row cap (--mcp-max-rows). 0 means the default. The totals beside each list always count everything. |
50 rows per list |
The questions it answers. Is proxy seven still sending? Read its row's
silent and idle_seconds. Why does the new PBX not show up? Look for its
address under refused_sources: auth_mismatch is the wrong shared secret,
auth_missing a sender with no key at all, allowlist an address --hep-allow
does not cover, and hmac_timestamp_out_of_window a sender whose clock has
drifted.
identity is always claimed_by_sender. One shared secret serves the
whole listener, so any sender holding it can claim any capture id. The roster
reports what senders say about themselves.
Silent is not down. A sender is silent once the listener has admitted
nothing from it for silence_threshold_seconds (--hep-silence-warn). A PBX with no
calls at night may send nothing at all.
No listener, no roster. A server with no -L returns listening: false
and a note:
this run has no HEP listener (-L/--hep-listen), so there are no senders to report
Every value is sipnab's own count, a claimed id, an address or a time, and no
byte of any packet, so the response carries no untrusted-content note. GET /v1/hep/senders returns the same fields and values for the same
roster. The MCP answer differs in two ways: its keys are in alphabetical order,
and it adds source_exhausted and source_stopped_early. --hep-senders
prints the roster at the end of a headless run.
fleet_inventory
What this sipnab process is, for a fleet controller that manages many instances: its build, the SHA-256 of its binary, its configuration as digests, its privilege, its uptime and its counters. Starts nothing and waits for nothing.
Parameters: none.
The example ran on 2026-11-03 with a development build, against
tests/pcap-samples/sip-rtp-g711.pcap
with --node-name edge-a --no-config:
// fleet_inventory {}
{
"schema_version": 1,
"node_name": "edge-a",
"build": {
"version": "0.5.232", "commit": "29204db7", "tag": "", "dirty": true,
"target": "aarch64-unknown-linux-gnu",
"features": ["api", "archive", "audio", "g729", "hep", "mcp", "mcp-http", "metrics",
"native", "opus", "plugins", "tls", "tui", "vcon"],
"version_line": "0.5.232 (29204db7-dirty) features: native,tui,audio,tls,hep,api,mcp,mcp-http,metrics,plugins,vcon,opus,archive,g729"
},
"binary": {
"sha256": "3242a3324b1c3ac762ba15d4f2eec3789a995533540b8aee56ec087afdc51ea8",
"error": null
},
"signature": {
"state": "unverified",
"note": "sipnab does not verify its own binary. Compare binary.sha256 with SHA256SUMS.txt of the release, after `gh attestation verify SHA256SUMS.txt --repo NormB/sipnab`."
},
"config": {
"recorded": true, "source": null, "shadowed": [], "file_sha256": null,
"parsed_sha256": "afa5e308cbb51683fe7ac0ca79e2a33f601530f33439211dd29586c9db0c7d75",
"argv_sha256": "cb86e74e2f7d2f54c2e75c3cb01976de06c9658406112c318c5f290cf606418d",
"effective_sha256": "aee2e58c08b314be6538cf9ccf1dfddb992992c4e7336a4d256373b67be72130"
},
"privilege": { "uid": 1000, "root": false, "dropped_to": null },
"process": { "pid": 3985285, "started": "2026-11-03T13:26:30Z", "uptime_seconds": 1 },
"interfaces": [],
"counters": {
"capture_packets_total": 852, "capture_sources_refused_total": 0,
"capture_backpressure_blocks_total": 0, "hep_export_failures_total": null,
"hep_export_dropped_total": null, "hep_export_queue_depth": null
},
"hep_listener": { "listening": false, "packets_refused": 0, "senders": [] }
}
- No configuration value and no command-line argument is in the answer, only their SHA-256 digests. A secret in either changes a digest and never appears.
signature.stateis alwaysunverified. Comparebinary.sha256with the release's attestedSHA256SUMS.txt.- Every field is the process's own claim.
GET /v1/inventory returns the same document, from the same builder. Unlike
most tools, the answer carries no source_exhausted or source_stopped_early:
it describes the process, not a result read from the capture. A read token
reaches this tool. Manage many
sipnab instances reads the REST route from every instance.
server_capabilities
What this binary can do, what this server permits and loaded, the limits it answers under, and which libpcap it captures through. Ask it before requesting decryption, HEP, a file export or a capture swap, to learn whether the build carries the feature and the operator enabled the flag, instead of learning it from a refusal.
No parameters. The example is a full-feature build replaying a file with no opt-in flags:
// server_capabilities {}
{
"schema_version": 1,
"version": "0.5.269",
"features": ["api", "archive", "audio", "bpf", "g729", "hep", "mcp", "mcp-http",
"metrics", "native", "opus", "plugins", "tls", "tui", "vcon", "wasm"],
"can_decrypt": true, // tls
"can_hep": true, // hep
"can_plugins": true, // plugins
"runtime": {
"mcp_file_root": null, // the --mcp-file-root directory when set
"mcp_allow_shutdown": false,
"mcp_allow_open_capture": false,
"mcp_allow_tls_capture": false,
"mcp_allow_save_findings": false,
"mcp_allow_relay_query": false, // true only on a live capture with --rtpengine-control
"mcp_allow_vcon_fetch": false, // true with --mcp-allow-vcon-fetch and a [vcon_fetch] url
"hep_delivery_trust": "port-gated-only", // hmac-verified, plain-secret or port-gated-only
"mcp_allow_actions": [] // ["tfps"] with --allow-action tfps:mcp
},
"libpcap": {
"banner": "libpcap version 1.10.4 (with TPACKET_V3)",
"version": "1.10.4", // null when the banner carries none
"named_backends": [] // ["netmap"] when the banner names netmap
},
"limits": {
"max_rows": 1000, // --mcp-max-rows
"max_body_bytes": 4096, // --mcp-max-body-bytes
"max_inline_media_bytes": 5242880, // --vcon-max-inline-media; null without vcon
"max_wait_seconds": 60 // --mcp-max-wait-seconds
},
"tools": [ // what tools/list returns
"actions_revert", "aggregate_dialogs", "analyze_vcon", "await_condition",
"build_evidence_package", "cancel_find_in_captures", "capture_health",
"capture_status", "check_codec_negotiation", "compare_captures", "compare_dialogs",
"decode_evidence", "decode_ng", "describe_endpoint", "diagnose_registration",
"evaluate_expectations", "explain_attribution", "explain_response_code",
"explain_rule", "export_audio", "export_capture", "export_vcon", "fetch_vcon",
"find_correlated", "find_in_captures", "find_in_captures_status", "find_problems",
"fleet_inventory", "generate_fail2ban_rule", "generate_repro", "generate_wireshark_filter",
"get_call_tree", "get_capture_report", "get_dialog", "get_dialog_report",
"get_message", "get_sdp_timeline", "group_dialogs", "hep_senders", "lint_dialog",
"list_captures", "list_dialogs", "list_tls_libraries", "media_diagnostics",
"open_capture", "query_relay", "reconcile_orphans", "relay_compare", "relay_stats",
"render_ladder", "rtp_stats", "runtime_stats", "save_findings", "search_by_time",
"search_messages", "security_findings", "server_capabilities", "show_evidence",
"shutdown_server", "siprec_metadata", "start_tls_capture", "stop_tls_capture",
"tail_dialogs", "tfps_ban", "tfps_banned", "tfps_dropped", "tfps_labels",
"tfps_status", "tfps_unban", "th_mappings", "timeline", "top_talkers", "triage_call",
"validate_filter", "validate_message", "validate_vcon", "vcon_directory_report",
"vcon_spool_status"
],
"bundles": [ // bundles loaded whole
"core", "signaling", "captures", "security", "media", "relay", "tfps", "server",
"vcon", "tls"
],
"prompts": [ // what prompts/list returns
"triage-outage", "carrier-escalation", "codec-interop-audit",
"post-change-verification", "vcon-handoff"
],
"resource_templates": [ // what resources/templates/list returns
"sipnab://live/dialogs/{call_id}", "sipnab://lint/{rule_id}",
"sipnab://filter/{alias}", "sipnab://reference/{topic}", "sipnab://schema/{tool}",
"sipnab://vcon/{call_id}"
]
}
runtime.mcp_allow_relay_query is true only when query_relay,
relay_stats and relay_compare can actually transmit: the run reads a live
interface, --rtpengine-control names the relay, and the operator passed
--mcp-allow-relay-query. A file replay never transmits, so the flag alone
does not set it.
runtime.mcp_allow_vcon_fetch is true only when
fetch_vcon can reach a store: the operator
passed --mcp-allow-vcon-fetch and the config file sets [vcon_fetch] url.
Reporting it contacts no store.
runtime.mcp_allow_actions lists the action targets --allow-action enabled
for MCP callers, by name.
limits are the ceilings this server holds every response to, as the operator
set them. Response bounding says what each one bounds.
tools is the loaded tool set after --mcp-tools selected it. bundles lists
each built-in bundle whose tools all appear in tools, counting only the tools
this build carries, so a selection of single tool names lists no bundle those
tools only partly fill. prompts and resource_templates are the names prompts/list and
resources/templates/list return, in the same order.
features lists the features compiled into this binary. runtime reports
what the operator enabled on this server.
hep_delivery_trust says what an endpoint a relay asserted over HEP is worth on
this run, decided once at startup by the HEP listener's authentication:
hmac-verified with --hep-auth-mode hmac and a secret, plain-secret with a
secret and the default plain mode, and port-gated-only when sipnab checks no
secret, which includes every run that does not listen for HEP. An endpoint the
HEP listener delivered carries the same value in its delivery_trust. A HEP
datagram read off a capture interface or a file, --hep-parse included,
reached no listener and is port-gated-only.
libpcap reports the libpcap this process loaded, as pcap_lib_version()
returns it. A gnu build or a package loads the host's libpcap, a static musl
build carries its own, and a macOS build loads the one macOS ships, so the
same sipnab version can report different libraries on different hosts.
named_backends lists the alternate capture backends (netmap, dpdk,
dag, snf) that the banner names. It matches the second line of
sipnab --version and the libpcap block of REST GET /v1/capabilities.
A backend missing from it may still be present: libpcap names netmap in its banner only from 1.10.6, and DPDK only in a DPDK-only build. Which capture backends an artifact can reach has the per-artifact table.
Capture control (opt-in, off by default)
The tools that change server state rather than read it. Every one stays off until you turn it on server-side.
shutdown_server
Destructive. Requires --mcp-allow-shutdown, which is off by default.
Without it every call fails, whatever the arguments say:
shutdown is disabled: start sipnab with --mcp-allow-shutdown to permit it. A stock server cannot be stopped by an agent.
It arrives as invalid_params (-32602) with data.reason: "not_enabled".
| Name | Type | Legal values | If omitted |
|---|---|---|---|
dry_run? |
bool? | true reports what would happen. false stops the process. |
true — the safe value is the default, so stopping takes a deliberate second call. |
save_to? |
string? | A bare filename inside --mcp-file-root to write the capture to before stopping. |
sipnab writes nothing. On a live capture holding unsaved packets, the call then refuses unless discard_unsaved is true. |
discard_unsaved? |
bool? | true accepts losing the packets a live capture holds in memory. |
false — a live capture with unsaved packets refuses to stop. |
Returns dry_run, would_stop, live, unsaved, dialogs, streams,
saved_to, confirmed_by_operator, note, source_exhausted,
source_stopped_early and schema_version. Read
would_stop rather than assuming: it is false on a dry run, on a refusal and
on a declined confirmation alike, and note says which.
// shutdown_server {} — no arguments means DRY RUN
{
"schema_version": 1,
"dry_run": true,
"would_stop": false,
"live": false,
"unsaved": false,
"dialogs": 2,
"streams": 2,
"saved_to": null,
"confirmed_by_operator": null,
"note": "dry run — nothing stopped. Call again with dry_run=false to stop.",
"source_exhausted": true,
"source_stopped_early": false
}
Stopping takes a second call with dry_run: false, which answers
"would_stop": true and "note": "shutdown requested", and the process
exits. On a live capture holding packets written nowhere, it refuses
unless you pass save_to or discard_unsaved: true.
Where the client can carry the question, sipnab asks a person. If your
client declared MCP's elicitation capability, a dry_run: false call sends a
real elicitation/create request and waits for the answer. Only accept
carrying confirm: true stops the process:
// shutdown_server { "dry_run": false }, confirmation declined
{
"schema_version": 1,
"dry_run": false,
"would_stop": false,
"live": false,
"unsaved": false,
"dialogs": 2,
"streams": 2,
"saved_to": null,
"confirmed_by_operator": false,
"note": "the confirmation was declined; nothing was done",
"source_exhausted": true,
"source_stopped_early": false
}
confirmed_by_operator is null where sipnab asked nobody — a dry run, or a
client that declared no elicitation capability. That case is not a
refusal: dry_run: false alone then stops the process. save_to writes only
on the path that
actually stops, so a declined confirmation leaves no file behind. See
the protocol page.