mcp-server-malcolm

Overview Schema Source Related Servers Discussions Admin

Find related sessions by UID

malcolm_related_sessions

Read-only

Pivot from a single Zeek connection UID to all directly and cross-referenced sessions, returning separate direct and related hit lists.

Instructions

Correlate one Zeek UID across sessions via both direct and cross-reference matches.

    Use this to pivot from a single connection UID to everything tied to it.
    "direct" is every record carrying the UID in zeek.uid: the conn record and
    its dns, http, ssl, files and other protocol records. "related" is every
    record whose rootId is the UID but whose zeek.uid is not, chiefly the
    connections carried inside a tunnel when the UID is the tunnel's. For an
    ordinary connection "related" is empty, which is the normal answer.
    Zeek UIDs only: to pivot from an Arkime session id use
    arkime_session_detail, and for a plain single-field query without the dual
    direct/related split use malcolm_search with a zeek.uid filter.

    Behavior: runs TWO independent Malcolm searches (one per match kind); `limit`
    caps EACH side separately, so up to 2×limit sessions come back total. The two
    searches fail independently — a failure on one side does not abort the other;
    instead the result carries a `direct_error` or `related_error` string in place
    of that side's hit list, and the summary names the side as failed rather than
    counting it; both failing is reported as an error, since nothing was
    correlated.
    Neither search is time-filtered — like malcolm_search, both cover all
    retained history, so an empty result is a real absence rather than a
    window. Returns a JSON object with separate "direct" and "related" hit
    lists plus a "summary" count (and per-side error keys only when a side
    fails). Malcolm reports no total, so the summary marks a side that
    filled `limit` as possibly holding more.

Input Schema

Name	Required	Description	Default
`uid`	Yes	Zeek connection UID as it appears in the zeek.uid field, e.g. "CExampleUid00001A". An Arkime session id (the "3@231115-..." form) is a different key and correlates nothing here.
`limit`	No	Max sessions to return per side (direct and related counted separately).

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.2.1Oct 17, 2026

changedInput schema / properties / uid / description

Previous value: -"Zeek connection UID as it appears in the zeek.uid field, e.g. \"CYeji2z7CKmPRGyga\". An Arkime session id (the \"3@240425-...\" form) is a different key and correlates nothing here."New value: +"Zeek connection UID as it appears in the zeek.uid field, e.g. \"CExampleUid00001A\". An Arkime session id (the \"3@231115-...\" form) is a different key and correlates nothing here."

Changed1 schema field changedv1.2.0Oct 3, 2026
- addedInput schema / properties / limit / maximum
```
Added value: +500
```

Changed1 schema field changedv1.0.2Jul 31, 2026

changedInput schema / properties / uid / description

Previous value: -"Zeek connection UID to correlate on, e.g. \"CYeji2z7CKmPRGyga\". Required (non-empty)."New value: +"Zeek connection UID as it appears in the zeek.uid field, e.g. \"CYeji2z7CKmPRGyga\". An Arkime session id (the \"3@240425-...\" form) is a different key and correlates nothing here."

Changed3 schema fields changedv0.3.0Jul 26, 2026

addedInput schema / properties / limit / description

Added value: +"Max sessions to return per side (direct and related counted separately)."

addedInput schema / properties / limit / minimum
```
Added value: +1
```

addedInput schema / properties / uid / description

Added value: +"Zeek connection UID to correlate on, e.g. \"CYeji2z7CKmPRGyga\". Required (non-empty)."

First observedv0.1.0Jul 24, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only cover the safety profile (readOnly, non-destructive, open-world), so the description carries the real behavioral burden and does so richly: two independent searches, `limit` capping EACH side so up to 2×limit results, per-side independent failure with direct_error/related_error keys, and no time filtering. This is exactly the operational context an agent needs before invoking.

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

Conciseness4/5

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

The purpose and pivot guidance are front-loaded before the behavioral detail, and each paragraph covers a distinct concern (what direct/related mean, alternatives, execution behavior, return shape). It is long, but for a tool with dual independent searches and per-side failures, nearly every sentence carries load; only mild trimming would be possible.

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?

Despite an output schema existing, the description explains the return contract (direct/related hit lists, summary count, per-side error keys) and the all-history scope, so an agent understands empty vs. failed vs. truncated results. Nothing needed to call it correctly or interpret results is missing.

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

Parameters4/5

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

Schema coverage is already 100%, but the description adds real meaning beyond it: it clarifies that `limit` caps each side separately (so 2×limit total), and reinforces the uid semantics by warning that an Arkime session id correlates nothing. That goes beyond the schema's field-level text, though it is reinforcement rather than new syntax.

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?

States a specific verb and resource — correlating one Zeek UID across sessions via direct and cross-reference matches — and defines what 'direct' and 'related' mean precisely. It explicitly distinguishes itself from arkime_session_detail (Arkime session ids) and malcolm_search (plain single-field query), so an agent can tell it apart from siblings without opening schemas.

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?

Names the trigger ('pivot from a single connection UID to everything tied to it') and routes to the correct alternatives for adjacent needs (arkime_session_detail for Arkime session ids, malcolm_search for a plain zeek.uid filter). It even states the normal expected outcome ('for an ordinary connection related is empty, which is the normal answer'), which prevents misinterpreting a valid empty result.

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

Deploy Server