Skip to main content
Glama
Sign In
nagameTW

mcp-server-malcolm

by nagameTW
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Build connection graph

arkime_connections
Read-only

Build a source/destination connection graph to trace lateral movement or map which hosts a suspect IP communicated with.

Instructions

Build a source/destination connection graph of who talked to whom.

    Returns nodes and links between two fields — useful for tracing lateral
    movement or mapping which hosts a suspect IP communicated with. NOTE the
    src/dst fields take Arkime *db* names (srcIp, dstIp, dstPort, node) or
    the dotted storage paths (source.ip, destination.port), which resolve to
    the same graph; the one vocabulary this route rejects is the expression
    names arkime_sessions uses in `expression` (ip.src, port.dst). For
    distinct field-tuple pairs as text rather than a graph use
    arkime_multiunique; for a nested top-N hierarchy use
    arkime_spigraphhierarchy. Returns the raw Arkime connections response
    (nodes and links).

    The graph is drawn from `sessions` of the matching sessions, not from
    all of them. When more sessions matched than were used, a "Note:" line
    above the JSON gives both numbers; narrow with expression or raise
    sessions before reading a sparse graph as "these are the only hosts
    talking".

Input Schema

NameRequiredDescriptionDefault
time_toNoEnd time as EPOCH SECONDS (NOT a dateparser string). Empty = now.
sessionsNoHow many matching sessions the graph is drawn from (Arkime's length; its own default is 100). More sessions find more hosts and take longer: on Malcolm's training instance a query matching 41,768 sessions drew 8 nodes from 100 sessions, 23 from 10,000 (1.4 s) and 39 from 50,000 (3.5 s).
dst_fieldNoArkime db field for destination nodes (default dstIp; dstPort graphs by port instead of by host). Same vocabulary as src_field: db column or dotted storage path, never the exp column.dstIp
src_fieldNoArkime db field for source nodes (default srcIp). Common choices: srcIp, dstIp, dstPort, node — arkime_field_search's db column. The dotted storage path works here too and gives the identical graph: srcIp/dstIp and source.ip/destination.ip draw the same nodes and links. What this route will NOT take is the exp column: srcField=ip.src gets HTTP 403 and dstField=port.dst HTTP 500 "TypeError: Cannot read properties of undefined", so the expression names whose db spelling differs are refused here before the request is sent.srcIp
time_fromNoStart time as EPOCH SECONDS (NOT a dateparser string). Empty = Arkime's recent-only default.
expressionNoOptional Arkime expression syntax to scope the graph. Empty = all sessions.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.2.1
    • changedInput schema / properties / dst_field / description
      Previous value: -"Arkime db field for destination nodes (default dstIp; dstPort graphs by port instead of by host — measured on Malcolm v26.07.1, srcIp/dstPort returned 15 nodes and 11 links against srcIp/dstIp's 10 and 8). Same vocabulary as src_field: db column or dotted storage path, never the exp column."New value: +"Arkime db field for destination nodes (default dstIp; dstPort graphs by port instead of by host). Same vocabulary as src_field: db column or dotted storage path, never the exp column."
    • changedInput schema / properties / src_field / description
      Previous value: -"Arkime db field for source nodes (default srcIp). Common choices: srcIp, dstIp, dstPort, node — arkime_field_search's db column. The dotted storage path works here too and gives the identical graph: measured on Malcolm v26.07.1 over one 24-hour window, srcIp/dstIp and source.ip/destination.ip both returned 10 nodes and 8 links. What this route will NOT take is the exp column: srcField=ip.src returned HTTP 403 and dstField=port.dst HTTP 500 \"TypeError: Cannot read properties of undefined\", so the sixteen expression names whose db spelling differs are refused here before the request is sent."New value: +"Arkime db field for source nodes (default srcIp). Common choices: srcIp, dstIp, dstPort, node — arkime_field_search's db column. The dotted storage path works here too and gives the identical graph: srcIp/dstIp and source.ip/destination.ip draw the same nodes and links. What this route will NOT take is the exp column: srcField=ip.src gets HTTP 403 and dstField=port.dst HTTP 500 \"TypeError: Cannot read properties of undefined\", so the expression names whose db spelling differs are refused here before the request is sent."
  2. Changed1 schema field changedv1.2.0
    • addedInput schema / properties / sessions
      Added value: +{
+  "default": 10000,
+  "description": "How many matching sessions the graph is drawn from (Arkime's length; its own default is 100). More sessions find more hosts and take longer: on Malcolm's training instance a query matching 41,768 sessions drew 8 nodes from 100 sessions, 23 from 10,000 (1.4 s) and 39 from 50,000 (3.5 s).",
+  "maximum": 100000,
+  "minimum": 1,
+  "title": "Sessions",
+  "type": "integer"
+}
  3. Changed2 schema fields changedv1.0.2
    • changedInput schema / properties / dst_field / description
      Previous value: -"Arkime DB field for destination nodes (default dstIp; use dstPort to graph by port). Arkime db name only, NOT a dotted ECS name."New value: +"Arkime db field for destination nodes (default dstIp; dstPort graphs by port instead of by host — measured on Malcolm v26.07.1, srcIp/dstPort returned 15 nodes and 11 links against srcIp/dstIp's 10 and 8). Same vocabulary as src_field: db column or dotted storage path, never the exp column."
    • changedInput schema / properties / src_field / description
      Previous value: -"Arkime DB field for source nodes (default srcIp). Use an Arkime db name (srcIp, dstIp, dstPort, node) — NOT a dotted ECS name like ip.src."New value: +"Arkime db field for source nodes (default srcIp). Common choices: srcIp, dstIp, dstPort, node — arkime_field_search's db column. The dotted storage path works here too and gives the identical graph: measured on Malcolm v26.07.1 over one 24-hour window, srcIp/dstIp and source.ip/destination.ip both returned 10 nodes and 8 links. What this route will NOT take is the exp column: srcField=ip.src returned HTTP 403 and dstField=port.dst HTTP 500 \"TypeError: Cannot read properties of undefined\", so the sixteen expression names whose db spelling differs are refused here before the request is sent."
  4. Addedv0.3.2
  5. Removedv0.3.0
  6. First observedv0.1.0

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that - the graph is drawn only from `sessions` of the matching set, a "Note:" line reports matched vs. used counts, and rejected field spellings fail with specific status codes before the request is sent. It does not, however, cover pagination, node/link shape, or rate limits, so this is solid but not exhaustive.

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 purpose and alternatives, and the cautionary paragraph on sparse graphs is genuinely valuable. It loses a little to redundancy: the src/dst vocabulary rules and the sessions-cost framing are restated from the schema descriptions, so some sentences duplicate structured data rather than adding to it.

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, so return values need no prose. What an agent still needs - which field vocabularies work, why a graph may be sparse, how to see matched-vs-used counts, and which sibling covers a non-graph variant - is all present, making this complete for a read-only graph endpoint.

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 and the structured fields already carry the per-parameter detail (including the timing benchmarks on `sessions`). The description still earns credit above baseline by explaining that src/dst db names and dotted storage paths resolve to the identical graph, and that the expression-name vocabulary is refused - a cross-parameter constraint that is easy to miss field-by-field.

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?

Opens with a concrete verb and resource: "Build a source/destination connection graph of who talked to whom." It explicitly names the two closest siblings it is NOT (arkime_multiunique for text tuples, arkime_spigraphhierarchy for nested hierarchy), so an agent can route correctly 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?

Gives explicit alternatives with the condition that selects each: multiunique for "distinct field-tuple pairs as text rather than a graph," spigraphhierarchy for "a nested top-N hierarchy." It also states when to narrow (expression or raise sessions) before reading a sparse graph.

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

Deploy Server

Other Tools