mcp-server-malcolm

Overview Schema Source Related Servers Discussions Admin

Fetch a file carried by ONE session

arkime_session_file_by_hash

Read-only

Fetch metadata only for a file carried by a specific session using its md5 or sha256 hash, confirming the correct transfer when multiple sessions share a hash.

Instructions

Fetch the file one NAMED session carried, by content hash; returns METADATA ONLY.

    Session-scoped, which is the whole difference from arkime_file_by_hash:
    that one serves the most recent body carrying the hash across all
    sessions, so once a file has moved twice it answers about the wrong
    transfer. Prefer this whenever you hold a session id: this route can
    serve the body from each session that carried a hash while the sibling
    answers found:false, "No match found." for the same hash. Use
    malcolm_extract_file instead when Zeek carved the file to disk — that
    needs no session, but only works where file extraction is enabled.

    The bytes never enter the response and nothing is written to disk: a
    carved file may be live malware. The md5 and sha256 returned are
    computed over the bytes Arkime actually served, so comparing them with
    the hash you asked for shows whether the reconstructed body is complete.
    A hash this session did not carry is a successful answer with
    found:false, not an error — Arkime's own 400 "No match" — while a body
    over 100 MB is refused, url_only being the way through.

Input Schema

Name	Required	Description
`node`	No	Capture node that recorded the session (the `node` field of the arkime_sessions row). Empty resolves it from the session document, one extra request, and is also done for url_only.
`url_only`	No	If true, return only the download URL and skip the download.
`file_hash`	Yes	Content hash of the carried body: md5 (32 hex chars) or sha256 (64). It lives in this session's own http.md5 / http.sha256, which malcolm_search returns and arkime_session_detail does not (that row carries http.uri but no hash). A hash from a different session is answered "no match" even though the file exists elsewhere.
`session_id`	Yes	The session that carried the file, from an arkime_sessions row. This is what makes the answer specific: the same file moving five times has five sessions, and this asks about one of them.

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 / file_hash / description

Previous value: -"Content hash of the carried body: md5 (32 hex chars) or sha256 (64). It lives in this session's own http.md5 / http.sha256, which malcolm_search returns and arkime_session_detail does not (measured on Malcolm v26.07.1: that row carries http.uri but no hash). A hash from a different session is answered \"no match\" even though the file exists elsewhere."New value: +"Content hash of the carried body: md5 (32 hex chars) or sha256 (64). It lives in this session's own http.md5 / http.sha256, which malcolm_search returns and arkime_session_detail does not (that row carries http.uri but no hash). A hash from a different session is answered \"no match\" even though the file exists elsewhere."

Addedv1.0.2Jul 31, 2026

TDQS

A4.4/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered by structured data. The description adds real context beyond them: bytes never enter the response, nothing is written to disk (malware caution), found:false is a successful answer rather than an error, bodies over 100 MB are refused, and the returned md5/sha256 are recomputed over the served bytes. Rich and non-contradictory, but it sits on top of annotations that already carry the safety story.

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 first line front-loads the verb, scope and return shape, which is exactly right. The remaining prose is dense but almost every sentence carries a distinct constraint (routing, malware, hash verification, 100 MB cap); the only cost is the heavily indented multi-paragraph layout and the trailing whitespace, which make it longer to parse than necessary.

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?

An output schema exists, yet the description still resolves the ambiguity an agent would hit in practice: found:false is not an error, and the hash comparison is a completeness check. For a session-scoped metadata fetch, nothing needed to call it correctly 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 tying url_only to the >100 MB refusal ('url_only being the way through') and noting that an empty node costs one extra request. These are operational details about parameter use rather than restatements, but they are brief relative to the schema's own per-parameter text.

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 (fetch) and resource (the file one NAMED session carried), plus the return shape ('METADATA ONLY'). It explicitly contrasts with arkime_file_by_hash and malcolm_extract_file, so an agent can distinguish it from siblings without opening a schema.

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 alternatives and the exact conditions that select them: 'Prefer this whenever you hold a session id' vs. arkime_file_by_hash for most-recent-across-sessions vs. malcolm_extract_file when Zeek carved the file to disk. It also gives a concrete failure mode of the sibling ('answers found:false for the same hash'), which is unusually actionable routing guidance.

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

Deploy Server