MCP Tools - NormB/sipnab GitHub Wiki

Every tool the MCP server exposes, grouped by bundle. This page does four things:

• it says what a bundle is,
• it lists the bundles,
• it finds any tool by name,
• it states the rules every tool follows.

Each bundle's page documents what its tools answer and what they return.

This is lookup material, not reading material.

• MCP server — what MCP is, and a first working example.
• MCP deployment — the deployment shapes.
• MCP protocol — the wire contract, security model and error semantics.

No tool edits the analysis in place, and every response carries a row ceiling.

That ceiling defaults to 1000 rows and is an operator setting:

• Set it with --mcp-max-rows N, or [limits] mcp_max_rows in the config file. The flag wins.
• Lower it for a model with a small context window; raise it for a batch client that writes answers to a file.
• It is a different limit from dialog_limit (--limit, default 100000), which bounds the dialogs tracked over the whole run.

One tool replaces the analysis outright: open_capture, off unless you enable it. It mints a new capture identity. So the replacement cannot reach a consumer as an ordinary update.

A bundle is a named set of tools defined in sipnab's code.

• Every tool is in exactly one bundle. So the ten bundles together are every tool the server has.
• --mcp-tools loads bundles by name, as Choosing which tools load describes.
• Each bundle has a page that documents its tools.

Every tool the server registers sends its name, description and schemas to the client on tools/list. The client keeps them in the model's context for the whole session. The client pays that cost before the agent asks anything. So give a client that needs a few tools only those few:

sipnab -N -I capture.pcap --mcp --mcp-tools core,relay,get_sdp_timeline

--mcp-tools (or [mcp] tools in the config file) takes a comma-separated list of:

• bundles, from the bundle table. Every tool is in exactly one, so the bundles together are full.
• single tool names, for one tool from a bundle you do not want whole.
• your own bundles, defined under [mcp.bundles] in the config file.
• full, every tool. This is the default.

sipnab refuses to start, exit 2, when a name is unknown or empty, and lists the valid bundles. Names are case-sensitive. With --mcp-tools core,bogus:

--mcp-tools: unknown tool or bundle 'bogus'; bundles: core, signaling, captures, security, media, relay, tfps, server, vcon, tls, or full; tool names are listed in the MCP tool reference

The handshake's instructions string names the tools sipnab loaded and the bundles it left out, so an agent that misses a tool can tell the operator which bundle to add. Under --mcp-tools core it ends:

Tools loaded: core. Other bundles, which the operator can add with --mcp-tools or [mcp] tools: signaling, captures, security, media, relay, tfps, server, vcon, tls.

Output schemas are off by default.

• MCP makes them optional, and they are more than half the bytes.
• Every response carries the same JSON with or without them, as a text block and as structuredContent.
• Only a client that validates responses against a declared shape needs them.
• Turn them on with --mcp-output-schemas or [mcp] output_schemas = true.

You can read one tool's response shape without turning output schemas on for every tool. Read the resource sipnab://schema/<tool>. It returns one of these:

• the tool's output JSON Schema and an example payload generated from that schema,
• a statement that the tool declares no output schema.

Tool response schemas describes the resource.

Bytes are the compact JSON of each tool's tools/list entry, summed over the bundle.

Measured on sipnab 0.5.222 on a build with every feature.

• Sizes, tool counts and bundle membership may change in later releases.
• A build without a feature does not register that feature's tools, so its bundles are smaller.

Every tool in alphabetical order, with the bundle that holds it. The tool name links to its section on the bundle's page.

Seven tools select calls, and each answers a different question.

A filter is one of these:

• an expression in sipnab's filter language (the DSL), such as state == Failed. A value may be bare or quoted: method == INVITE and method == 'INVITE' are the same filter,
• the name of a built-in alias such as problems.

A prompt is a named list of steps. It tells a model which tools to call and in what order. A client lists them with prompts/list and fetches one with prompts/get. No prompt takes arguments, and every tool stays callable without one.

Each prompt's steps:

• triage-outage:

  • read unanalysed_sip_messages from capture_status first;
  • get the shape of the failure from find_problems;
  • run triage_call on one Call-ID from that result;
  • follow its frame pointer with show_evidence before stating that a message caused the failure.

• carrier-escalation:

  • capture_status;
  • group_dialogs by next_hop with the asr and ner metrics, reading the population block;
  • get_call_tree on an affected Call-ID, because carrier faults usually span several legs;
  • build_evidence_package for the calls the escalation cites.

• codec-interop-audit:

  • capture_status;
  • check_codec_negotiation for offers with no common codec;
  • group_dialogs by rtp.codec with mos_p10;
  • media_diagnostics on a call that negotiated a codec and still sounded wrong.

• post-change-verification:

  • capture_status;
  • compare_captures against the baseline from before the change;
  • evaluate_expectations when the repository has a rules file;
  • timeline to check the failures did not move to a different hour.

• vcon-handoff:

  • capture_status;
  • validate_filter on the filter that selects the calls;
  • export_vcon with that filter;
  • validate_vcon on each exported container, passed as container;
  • then record each container's digest (its SHA-256) and Call-ID.

  Passing call_id to validate_vcon instead exports a second container with a different creation time. So its digest differs from the one sent.

sipnab serves a prompt only when the server registers every tool it calls.

• Under --mcp-tools core, prompts/list returns no prompt. Each one calls at least one tool outside core.

• prompts/get refuses a prompt it does not serve with error -32602. The message names the tools the server does not load and the bundles that hold them:

  {"code":-32602,"message":"prompt 'triage-outage' is not served: it calls show_evidence, which this server does not load. Add the bundle(s) captures with --mcp-tools or [mcp] tools. Served: ","data":{"param":"name","reason":"not_enabled"}}

• A tool the build does not carry also hides the prompts that call it.

Seven rules hold across the whole surface. Each tool section on a bundle page states only what its tool does differently. So read these once and skip them afterwards.

A required parameter has no default.

• Leave one out, or send the wrong JSON type, and the tool does not run. The call fails with invalid_params (-32602), data.reason "invalid_arguments", and a message that names the field, for example failed to deserialize parameters: missing field `call_id` .
• A value of the right type that the tool cannot use (an unknown choice, a range it does not accept) fails with invalid_params (-32602), and data.reason says which; see Error data.
• Optional parameters carry a ? in every parameter table.
• Each row says what the tool does when you omit that one.

A limit of 0 means the default, not "no rows".

• limit defaults to 50 everywhere it appears.
• The server clamps anything larger to --mcp-max-rows (1000 unless the operator lowered it). It returns the clamped page without an error.
• Both edges bite the same caller:
  • A client that computes limit from "rows I still want" asks for 50 when it meant to ask for none.
  • A client that asks for 5000 to "get everything" receives 1000 and no complaint.
• Read returned rather than the length you asked for.

Pass a cursor back exactly as it arrived. next_cursor pairs a timestamp with an identity:

• <RFC 3339>|<Call-ID> for dialogs,
• <RFC 3339>|<Call-ID>#<message index> for search_messages hits and get_dialog messages,
• <RFC 3339>|0xSSRC@src>dst for the rtp_stats sweep and reconcile_orphans.

A hand-rebuilt bare timestamp still parses on the dialog tools. So rebuilding one costs rows instead of raising an error. next_cursor: null marks the final page.

A page ends at the first bound it reaches, and says which. Two bounds apply to every paged tool:

• the row limit (limit, clamped to --mcp-max-rows),
• the byte budget (max_response_bytes, clamped to --mcp-max-response-bytes, 1048576 bytes unless the operator changed it).

Either one does three things:

• sets truncated: true,
• names itself in truncated_by (rows or bytes),
• leaves a next_cursor that resumes at the first row the page left out.

truncated_by is absent when neither bound cut the page.

The byte budget works like this:

• It drops whole rows from the end of the page and never part of one.
• A page always keeps at least one row. So following the cursor always moves forward, even when one row alone is larger than the budget.
• It counts the bytes the sipnab_mcp_tool_response_bytes_total metric counts: the JSON page, the provenance note and the two completeness booleans below.
• The JSON-RPC framing and the structuredContent copy of the page are not counted.
• Every paged tool takes it: list_dialogs, find_problems, search_by_time, search_messages, tail_dialogs, get_dialog, reconcile_orphans and the rtp_stats sweep.

Every list-style tool answers with a page object, never a bare array.

• The rows sit under a named key (dialogs, hits, streams, findings) beside returned and total_matched.
• So counting the rows is never necessary and never right.
• search_messages and security_findings carry the page fields too.
• tail_dialogs is the one page object with no total, because a tail cannot have one. Response bounding tabulates it.

Every answer says how much of the capture is behind it. Two booleans ride on every response object:

• source_exhausted, true once sipnab has read the source to its end,
• source_stopped_early, true when a read ended before the source did. Causes are a truncated dump file, a file that would not open, or a read error part-way through.

The answer is the WHOLE answer only when source_exhausted is true and source_stopped_early is false. One response tells you that much. So nothing has to call capture_status to interpret it.

Until then the response omits truncated: false entirely.

• That value claims outright that the page holds every match.
• A caller reading only that field deserves no claim rather than a wrong one. JSON absence and false are different values.
• The response still says truncated: true whenever the row cap really did keep matches out. That fact holds whatever the load state.
• complete, where a tool has one, likewise never reads true over a partial read.

A file source loads on a background thread, so a call made right after the server starts can answer from part of the file. This sends list_dialogs with no pause, against a sample capture that holds 1334 dialogs:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"shell","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_dialogs","arguments":{}}}' \
  | sipnab --mcp -N -I tests/pcap-samples/sipp-branch-scenario.pcapng --quiet \
  | jq -c 'select(.id == 2) | .result.content[0].text | fromjson | {returned, total_matched, truncated_by, source_exhausted}'

{"returned":33,"total_matched":33,"truncated_by":null,"source_exhausted":false}

jq prints null for truncated_by because the response leaves that field out. The counts vary from run to run with how far the load had got. The same call sent two seconds after notifications/initialized:

{"returned":50,"total_matched":1334,"truncated_by":"rows","source_exhausted":true}

When source_exhausted is false, total_matched counts only what had loaded. Repeat the call, or poll capture_status until source_exhausted reads true, before treating a count as final.

Twenty-one tools are the exception, because their answer cannot move with the load. How much of the capture sipnab has read says nothing about what their sources hold:

• Twelve read something other than the capture store:
  • explain_response_code, explain_rule, decode_evidence, decode_ng, show_evidence, list_captures, list_tls_libraries, server_capabilities;
  • vcon_spool_status, which counts the vCon export spool that the forwarder drains;
  • compare_captures, which reads two files and never the loaded capture;
  • analyze_vcon, which analyzes a container the caller hands over;
  • vcon_directory_report, which reads the containers in a directory of the file root.
• The other nine ask another process:
  • query_relay and relay_stats put the question to the media relay;
  • tfps_status, tfps_banned, tfps_dropped, tfps_labels, tfps_ban and tfps_unban put it to the toll-fraud prevention peer;
  • fetch_vcon puts it to the operator's vCon store.

The tools that answer with a rendered document have no object to put a field in. These are render_ladder, and get_capture_report / get_dialog_report in markdown and text. So they say it in prose instead.

• A document drawn over a capture that is still loading ends with the same INCOMPLETE RUN block --report appends, naming each reason.
• The same holds over a capture whose read stopped before its end.
• A document drawn over a capture read in full says nothing extra. A caveat on every answer is a caveat nobody reads.

Every other tool answers with a JSON object, and the two booleans sit in the object beside the tool's own fields. timeline, for example, returns its buckets inside an object that carries both.

Capture text arrives fenced, and identifiers do not.

• Free text an endpoint wrote comes wrapped in ⟦untrusted-capture-data⟧ … ⟦/untrusted-capture-data⟧. That covers display names, User-Agent, SDP and whole messages.
• The tools that emit it append a provenance note as the LAST content block.
• Call-IDs, cursors, addresses and timestamps stay verbatim. So they pass straight into the next call.

Untrusted capture text gives the per-tool breakdown. Every JSON sample on the bundle pages shows the markers where the server really emits them.

list_dialogs, find_problems, tail_dialogs and search_by_time take an optional fields array. Each row then carries only the fields you name, which makes a large page smaller. limit, --mcp-max-rows and cursors bound the number of rows, and fields bounds what each row carries.

Ask for two fields on each dialog in the paging sample capture from Reproduce the examples below:

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_dialogs","arguments":{"limit":2,"fields":["state","final_status_code"]}}}

The dialogs array in the answer:

[{"call_id":"[email protected]","final_status_code":403,"state":"Registered"},{"call_id":"[email protected]","final_status_code":403,"state":"Registered"}]

The rules:

• call_id is always kept, listed or not, so you can pass every row to a follow-up tool.

• An unknown name fails with invalid_params (-32602). The message and data.valid_values list the fields the row carries:

  {"code":-32602,"message":"unknown field 'stat'; this row carries: call_id, created_at, duration_sec, final_status_code, frame, from_user, input_origin, method, msg_count, state, timing, to_user, updated_at","data":{"param":"fields","reason":"invalid_choice","valid_values":["call_id","created_at","duration_sec","final_status_code","frame","from_user","input_origin","method","msg_count","state","timing","to_user","updated_at"]}}

• The page fields are always kept. total_matched, truncated, next_cursor and capture_identity stay on the response whatever fields names.

• A field a row does not carry stays absent. It does not appear as null.

These tools all require --mcp-file-root <DIR> and refuse to run without it:

• list_captures, export_capture, export_audio,
• compare_captures,
• build_evidence_package.

They take a bare filename, never a path.

• generate_repro joins them the moment you give it a filename.
• decode_evidence pushes the source half of a frame pointer through the same guard.

sipnab refuses ../x, /etc/passwd and sub/dir.pcap before any filesystem call, with invalid_params and data.reason path_refused:

{"code":-32602,"message":"'../x' is not a bare filename. These tools take a name, not a path, and write only inside the configured --mcp-file-root.","data":{"reason":"path_refused"}}

sipnab also refuses a symbolic link inside the root that resolves outside the root. It checks where the name points, not how the caller wrote it:

{"code":-32602,"message":"'link' resolves outside the configured --mcp-file-root. The name is a link to '/tmp', and these tools write only inside the root.","data":{"reason":"path_refused"}}

Each tool returns the resolved path of the file it wrote. Without --mcp-file-root, every file tool answers not_enabled:

{"code":-32602,"message":"file tools are disabled: start sipnab with --mcp-file-root <DIR> to enable them","data":{"reason":"not_enabled"}}

The boundary stops an escape, and an overwrite. Inside the root, these refuse a filename that already exists:

• export_capture, export_audio, build_evidence_package,
• generate_repro's filename,
• shutdown_server's save_to.

They name the file and ask for one that is free (data.reason already_exists). Choose another name, or call list_captures to see which names a directory already uses.

The guard covers every file in the root, not only the capture the run is reading: the captures staged there for open_capture and every earlier export keep their contents too.

find_problems.kinds — diagnostic alias names, OR-ed together. Defaults to ["problems"]. The full vocabulary:

problems · slow-setup · short-calls · one-way · nat-issues · codec-asym · ptime-asym · payload-asym · duration-asym · late-media

An unknown alias returns invalid_params (-32602) naming the alias, with the vocabulary in data.valid_values:

{"code":-32602,"message":"unknown alias 'bogus'","data":{"param":"kinds","reason":"invalid_choice","valid_values":["problems","slow-setup","short-calls","one-way","nat-issues","codec-asym","ptime-asym","payload-asym","duration-asym","late-media"]}}

The same names work as the list_dialogs filter aliases (and as sipnab --filter aliases on the CLI).

security_findings.kinds matches the rule names sipnab records findings under: scanner, fraud, digest, reg_flood.

• Write reg_flood with an underscore. The --alert rule grammar spells it reg-flood, but sipnab records and filters findings as reg_flood.

• Omitted or empty kinds returns findings of every kind.

• sipnab refuses an unknown name and lists the four names. For reg-flood the refusal also suggests the underscore spelling:

  {"code":-32602,"message":"unknown kind 'reg-flood', expected one of: digest, fraud, reg_flood, scanner (did you mean 'reg_flood'?)","data":{"reason":"invalid_value"}}

All tools return MCP errors via the JSON-RPC error object. The codes sipnab uses:

Tools never panic. An unknown Call-ID always produces a structured error rather than an empty result.

Every -32602 and -32000 error also carries a data object. So a client can act on the error without parsing message.

• The message text stays as it was.
• People read message, and its wording may improve between releases.
• The data codes below stay stable.

{
  "code": -32602,
  "message": "cannot group by 'bogus'; one of: state, response_code, ...",
  "data": {
    "reason": "invalid_choice",       // always present
    "param": "group_by",              // the argument that was refused, when one was
    "valid_values": ["state", "response_code", "method", "..."]  // the allowed set, when there is one
  }
}

sipnab omits a member that does not apply, rather than sending it as null.

Arguments that do not match a tool's input schema at all (a wrong JSON type, a missing required key) fail the same way, with invalid_arguments and the parse error as the message:

{"jsonrpc": "2.0", "id": 3, "error": {"code": -32602, "message": "failed to deserialize parameters: missing field `call_id`", "data": {"reason": "invalid_arguments"}}}

Set the ceilings for the client that reads the answers: lower for an agent with a small context window, higher for a batch client that writes answers to a file. Raise or lower them with --mcp-max-rows, --mcp-max-body-bytes and --mcp-max-response-bytes, or the matching [limits] keys in the config file. The per-call limit and max_response_bytes narrow an answer below the ceiling, and cannot exceed it.

The row and body ceilings bound a row's count and a body's width. Neither bounds the response as a whole.

• Fifty get_dialog messages that each carry a long SDP body are within both. They can still exceed what a small model can read.
• The byte budget covers that case. Its default is 1048576 bytes (1 MiB). Lower it per call with max_response_bytes, or for every call with --mcp-max-response-bytes.

A bound is not a loss. These tools each report total_matched beside their page:

• list_dialogs, find_problems, search_by_time, search_messages, security_findings,
• the capture-wide rtp_stats sweep.

So a caller sees how much of the answer it holds.

That number describes the STORE, not the file.

• While the source is still loading, it counts what had arrived by then.
• That is why every one of them also carries source_exhausted.
• It is also why the response omits truncated: false until the answer is whole.

All of those except security_findings carry a cursor to the rest. So do tail_dialogs, get_dialog and reconcile_orphans. Every one of the eight cursor tools takes max_response_bytes.

Asking for a limit above the ceiling does nothing, because the ceiling clamps it. So either raise the ceiling with --mcp-max-rows or page.

Some tools take limit and carry no cursor, and a caller has to know which:

aggregate_dialogs, group_dialogs and compare_captures take top_n rather than limit.

• They sum everything past it into other_count or other.
• So they withhold nothing silently, and have no cursor either.

tail_dialogs reports no total, because a tail cannot have one. The store keeps changing underneath it. So any number it gave would describe a moment that has passed.

Each tool section on a bundle page names the capture its example ran against. Start a server on that capture, then call the tool. These two cover most of the examples:

# The paging examples: 1334 dialogs, no RTP.
sipnab -N --mcp --mcp-transport http --mcp-bind 127.0.0.1:8731 \
       --mcp-file-root tests/pcap-samples \
       -I tests/pcap-samples/sipp-branch-scenario.pcapng

# The media examples: two calls (one completed, one still in progress at the end of the file) and two RTP streams.
sipnab -N --mcp --mcp-transport http --mcp-bind 127.0.0.1:8731 \
       --mcp-file-root tests/pcap-samples \
       -I tests/pcap-samples/sip-rtp-g711.pcap

Drive either one with the raw HTTP test on the deployment page, or point a client at http://127.0.0.1:8731/mcp. A loopback bind needs no token.

Numbers in the samples are what those captures produce. A file replay reads packet timestamps rather than arrival times, so jitter and MOS come out identical on every run. A value that does not match points at a change in the binary or the capture.