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 process and host is optional, because the sources are platform-specific.
  • host.basis names the denominator. Inside a container the basis reads cgroup and the totals come from the control group's memory.max, not the machine's memory.
  • impact.significant: true means sipnab's own memory use is load-bearing on this host, at or above the threshold note states (10% of the host memory total).
  • interfaces reads the network interface, not the capture handle. Compare the two to choose a remedy: ps_ifdrop climbing with rx_missed_errors means the NIC cannot keep up (adjust ring size, coalescing or RSS); ps_drop climbing alone means sipnab's read loop is falling behind (raise --buffer or 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_packets and capture_backpressure_blocks_total, rather than reporting 0.
  • Read occupancy against capacity. dialogs.pct and streams.pct near 100 mean the store is about to evict calls.
  • capture_identity names the capture dialogs.used and streams.used count. It is the identity capture_status reports, 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_dropped and in_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-tunnels and once without, and compare in_window.packets against 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 --mcp attached 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.state is always unverified. Compare binary.sha256 with the release's attested SHA256SUMS.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.