Skip to main content

SNMP4J MCP Capabilites

MCP Tool Key Capabilities Summary​

1. McpSnmpCommandGenerator​

  • Tool ID: snmp_command_generator
  • Description: Sends an SNMP PDU (GET, GETNEXT, GETBULK, SET, INFORM) to a configured SNMP target and returns the response as JSON.
  • Input Parameters:
    • targetName (required): Unique name of the SNMP target configuration
    • pdu (required): JSON object representing the SNMP PDU with type (GET | GETNEXT | GETBULK | SET | INFORM) and variableBindings array
  • SNMP Operations: GET, GETNEXT, GETBULK, SET, INFORM
  • Response: Returns JSON with targetName, peerAddress, error, durationNanos, request PDU, and response PDU (if successful)
  • Key Features: Supports SNMPv1/v2c/v3 with full variable binding type inference via SNMP4J string syntax (e.g., "string:hello", "integer:42", "oid:1.3.6.1"). PDU request/response JSON schemas are available as MCP resources.

2. McpSnmpMessageBER​

  • Tool ID: snmp_message_ber
  • Description: Parses a raw SNMP message (hex string) and returns its BER structure as text tree or JSON object tree.
  • Input Parameters:
    • hexMessage (required): Raw SNMP message as hex string (accepts colon-delimited, plain hex, or 0x-prefixed formats)
    • outputAsJSON (optional): When true, return BER tree as JSON object conforming to BER_RESULT_SCHEMA; when false (default), return indented text tree with box-drawing characters
    • useSpecifiedTargetsOnlyForDecryption (optional): Comma-separated list of SNMPv3 target names to use for decryption; empty to try all configured v3 targets
  • SNMP Operations: BER parsing/decoding only (NO network transmission)
  • Special Capability — DECRYPTION: When SNMPv3 targets with authoritativeEngineID are configured, the tool can decrypt AUTH_PRIV ScopedPDUs using credentials from matching targets. Supports both pre-localized keys (when engineID is known) and deferred localization (when engineID is extracted from the packet).
  • Authentication Algorithms Supported: MD5, SHA, SHA224, SHA256, SHA384, SHA512, HMAC variants
  • Privacy Algorithms Supported: DES, 3DES, AES-128, AES-192, AES-256
  • Critical Limitation: This tool does NOT send packets over the network. It only converts hex-encoded bytes to a human-readable BER tree structure and can decrypt encrypted payloads if credentials are available.

3. McpSnmpTable​

  • Tool ID: snmp_get_table
  • Description: Retrieves SNMP tabular data from a configured target and returns it as JSON with header row (column OIDs) and data rows.
  • Input Parameters:
    • targetName (required): Unique name of the SNMP target configuration
    • columnOIDs (required): Comma-separated list of columnar OIDs to retrieve
    • lowerBoundIndex (optional): Lower-bound row index OID (exclusive) for filtering
    • upperBoundIndex (optional): Upper-bound row index OID (inclusive) for filtering
    • contextName (optional): SNMPv3 context name
    • contextEngineID (optional): SNMPv3 context engine ID (hex string)
    • timeoutSeconds (optional): Maximum seconds to wait for retrieval
    • maxRows (optional): Maximum number of rows to return
    • includeOids (optional): Include full instance OID of each cell (default: false)
  • SNMP Operations: GETNEXT/GETBULK for table walks
  • Special Feature: Sends progress notifications to MCP client via McpSyncServerExchange.progressNotification() with row count during retrieval. Register with toSyncToolSpec() to enable progress reporting.
  • Response: JSON object with targetName, columns array, rows array (with index and cells), rowCount, and optional error message.

4. McpSnmpTree​

  • Tool ID: snmp_walk_subtree
  • Description: Walks an SNMP subtree rooted at a given OID using GETNEXT (SNMPv1) or GETBULK (SNMPv2c/v3) and returns all variable bindings as JSON.
  • Input Parameters:
    • targetName (required): Unique name of the SNMP target configuration
    • rootOID (required): OID of the subtree root to walk (root itself not included in result)
    • timeoutSeconds (optional): Maximum seconds to wait for walk to complete
    • maxVBs (optional): Maximum total number of variable bindings to return
    • maxRepetitions (optional): Maximum variable bindings per GETBULK request (ignored for SNMPv1)
  • SNMP Operations: GETNEXT (SNMPv1) or GETBULK (SNMPv2c/v3) for subtree walks
  • Special Feature: Sends progress notifications to MCP client with cumulative variable binding count after each batch. Register with toSyncToolSpec() for progress reporting.
  • Response: JSON object with targetName, rootOID, vbs array (variable bindings in depth-first order), vbCount, and optional error message.

5. McpSnmpModuleSupport​

  • Tool ID: snmp_detect_mib_modules
  • Description: Determines which loaded MIB modules are implemented by an SNMP target by probing table objects (via GETNEXT) and scalar objects (via GET) in breadth-first order.
  • Input Parameters:
    • targetName (required): Unique name of the SNMP target configuration
    • limit (optional): Maximum number of variable bindings per PDU (1–10, default 5). Higher values reduce round-trips at the cost of larger PDUs.
  • SNMP Operations: GET (scalars) and GETNEXT (tables)
  • Special Feature: Breadth-first scanning distributes probe load evenly across modules. Modules for which at least one object returns a valid value (non-exception, valid OID for GETNEXT) are reported as implemented.
  • Response: JSON object with targetName, moduleCount, limit, moduleList (comma-separated), and implementedModules array.
  • Requirement: Requires SmiManager to be initialized; MIB modules must be loaded before calling.

6. MibCompilerTool​

  • Tool ID: One of check_mib, check_mib_completely, or compile_mib (determined by TargetMode)
  • Description: Compiles SMIv1 or SMIv2 MIB specifications and returns compilation results as JSON.
  • Three Modes:
    • check_mib (dryRun): Syntax/semantic check, no repository changes
    • check_mib_completely (dryRunWithoutErrorLimit): Syntax/semantic check without error count limit
    • compile_mib (storeIntoRepositoryNoLoad): Compile, validate, and persist into repository (no cache load)
  • Input Parameters:
    • mibContent (required): MIB specification text (SMIv1 or SMIv2 format)
    • fileName (optional): Logical name for the MIB input (e.g., 'IF-MIB.txt') for identification in results
    • overwriteMode (optional, compile_mib only): 'addNewOnly' (default), 'overwriteIfNewer', 'overwriteAlways'
    • strictness (optional): 'standard' (default, full SMIv1/v2 checks) or 'lenient' (suppress standard violations)
  • Compilation Progress: Logged via server's logging infrastructure (INFO level) — not yet client-side MCP progress notifications, but extensible for future support.
  • Response: JSON array of compilation result objects with module names, error/warning lists, and success status.

7. MibSearchTool​

  • Tool ID: find_mib_objects
  • Description: Search for MIB definitions, modules, and objects using OIDs, names, types, and regular expressions.
  • Input Parameters:
    • operation (required): One of: findSmiObject, findSmiObjectType, findRootSmiObject, findSmiModule, findSmiModules, findSmiObjectByName, findSmiObjectsByType, findSmiObjectsByRegexMatching
    • oid (optional): Dotted-decimal OID for OID-based searches
    • moduleName (optional): MIB module name; search all modules if not specified
    • objectName (optional): Name of the object to search for
    • includeImportedModules (optional): Whether to search imported modules (default: false)
    • type (optional): SMI type filter (e.g., OBJECT_TYPE, OBJECT_TYPE_SCALAR, OBJECT_TYPE_TABLE, NOTIFICATION_TYPE)
    • smiObjectJsonPattern (optional): JSON object string with properties matching SmiObject and values as regex patterns
  • Search Operations: 8 distinct search operations via the operation parameter (OID-based, name-based, type-based, regex-based)
  • Response: JSON formatted results or error message; success message indicates number of objects found.

8. McpMibSemanticSearch​

  • Tool ID: semantic_search_mib
  • Description: Performs semantic (vector-similarity) search over all loaded MIB objects using natural language queries, understanding synonyms and paraphrases.
  • Input Parameters:
    • query (required): Natural-language description (e.g., 'interface throughput', 'system uptime')
    • limit (optional): Maximum number of results (1–100, default 10)
    • type (optional): SmiType filter substring (e.g., OBJECT_TYPE_SCALAR, OBJECT_TYPE_COLUMN, OBJECT_TYPE_TABLE, NOTIFICATION_TYPE)
    • syntax (optional): SmiSyntax filter substring (e.g., OCTET STRING, Integer32, Counter64, RowStatus)
  • How It Works:
    1. On first call, builds vector index by embedding every loaded MIB object using configured EmbeddingClient
    2. Persists index as GZIP'd JSON next to MIB repository for fast reload on server restart
    3. Embeds natural-language query and ranks objects by cosine similarity
  • Embedding Backend: Requires OPENAI_API_KEY environment variable (or openai.api.key JVM property) for OpenAI embeddings, or DJL ONNX dependencies for local embedding.
  • Response: JSON object with query, limit, typeFilter (if set), resultCount, and results array (each with score, name, oid, type, syntax, optional description snippet).
  • Lazy Index Build: First call returns immediately saying "index is being built, retry in a few seconds" if not yet ready; subsequent calls use cached index.

McpSnmpBuilder (Target/Session/PDU Builder)​

Purpose: Translates SnmpMcpServer.ServerConfiguration.SnmpTargetConfig into SNMP4J fluent-API objects (Target, Snmp, PduBuilder).

SNMP Versions Supported:

  • SNMPv1
  • SNMPv2c
  • SNMPv3 with full USM support

SNMPv3 Security Levels (via McpSnmpBuilder):

  • noAuthNoPriv (no authentication, no encryption)
  • authNoPriv (authentication only, via MD5/SHA/SHA2)
  • authPriv (authentication + encryption via DES/3DES/AES)

Key Methods:

  • buildTarget(): Constructs SNMP Target from config, adds necessary TransportMapping to SnmpBuilder, configures version/timeout/retries/auth/priv
  • buildSnmp(existingSnmp): Returns existing session if non-null, otherwise builds new Snmp instance
  • buildPdu(): Returns PduBuilder for constructing PDUs

Transport Support: Via SNMP4J's generic TransportMapping infrastructure — supports UDP (default), TCP, TLS, and other pluggable transports.

Key Security & Design Notes​

  1. McpSnmpMessageBER does NOT transmit packets — it only parses and decrypts existing hex-encoded SNMP message bytes. There is no method that sends packets over the network.

  2. Decryption requires matching credentials: When a hex message contains an encrypted SNMPv3 ScopedPDU, the tool attempts decryption using configured SNMPv3 targets' passphrases and engineIDs. This enables inspection of encrypted messages if the server has the agent's credentials.

  3. Progress notifications are available on McpSnmpTable and McpSnmpTree via toSyncToolSpec() registration, using McpSyncServerExchange.progressNotification().

  4. MIB semantic search is asynchronous — index building happens in background on first use; subsequent queries are fast and use cached index.

  5. All SNMP tools require targetName parameter pointing to a pre-configured target in the MCP server's configuration.