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 UID to all tied sessions: returns direct matches carrying the UID and related records under a tunnel UID.

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

TableJSON Schema

Name	Required	Description	Default
`uid`	Yes	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.
`limit`	No	Max sessions to return per side (direct and related counted separately).

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

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 already declare readOnlyHint/openWorldHint/destructiveHint=false, and the description goes well beyond them: two independent searches, limit applied per side (up to 2x total), independent per-side failure with direct_error/related_error keys, no time filtering across retained history, and a summary that flags a limit-filled side as possibly truncated. This is exactly the operational context an agent needs.

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?

Front-loaded with the core purpose, then alternatives, then behavior; every paragraph carries distinct information. It is on the verbose side, with some overlap between the uid schema note and the 'Zeek UIDs only' sentence, but nothing is filler.

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?

Even though an output schema exists, the description characterizes the result shape (separate direct/related hit lists, summary count, conditional per-side error keys) and the all-history, no-window behavior. Nothing needed to call or interpret the tool 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 100%, so the baseline is 3. The description still adds meaning by spelling out that limit caps EACH side separately, implying up to 2xlimit sessions total, and by restating the uid/Arkime-id distinction that the schema already documents.

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: correlate one Zeek UID across sessions via direct and cross-reference matches. It explicitly distinguishes itself from arkime_session_detail and malcolm_search, so an agent can select it without opening sibling 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?

Explicitly frames the use case ('pivot from a single connection UID to everything tied to it') and names the alternatives with the condition that selects them: arkime_session_detail for Arkime session ids, malcolm_search for a plain single-field zeek.uid query. It also pre-empts a false alarm by noting that an empty 'related' side is the normal answer.

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

Deploy Server