Netmon (demo)

Connect an AI assistant to a Netmon appliance.

Netmon ships an MCP server on the appliance itself. This repository holds the client-side bridge: a small Node process that runs on your own machine, speaks stdio to Claude Desktop, and forwards every JSON-RPC message to your Netmon's /mcp endpoint over HTTPS.

Once connected, an assistant can read your devices, interfaces, logs, flow records, alerts, and Windows-agent data by calling Netmon's tools directly — with the same sign-in and permissions as any operator, and the same tag restrictions.

• Product overview: https://netmon.com/netmon-ai-assistants/
• Setup guide: https://netmon.com/netmon-7-user-guide/api-and-integrations/
• API reference: https://netmon.com/api-reference/authentication/

---

Try it first — no appliance needed

A public, read-only demo server answers the same 36 tools from a recorded, de-identified snapshot of a fictional 90-device network:

https://netmon.com/mcp-demo/mcp

No account, no token, no install. Point any MCP client at it — in Claude Code:

claude mcp add --transport http netmon-demo https://netmon.com/mcp-demo/mcp

or in a client config:

{
  "mcpServers": {
    "netmon-demo": { "url": "https://netmon.com/mcp-demo/mcp" }
  }
}

Then ask it something real: "what's down?", "show me the Suricata alerts from last week", "which host is using the most bandwidth, and who is it talking to?"

It is a fixture, not an appliance: nothing writes, nothing reaches a real network, and every answer is the same shape a live Netmon returns — with timestamps shifted forward so the snapshot always reads as the last day or so.

---

Why a local bridge

Claude connects to remote MCP servers from Anthropic's cloud infrastructure, not from your machine. A Netmon appliance on a private network is not reachable from there.

The bridge runs as a local process, so it can reach the appliance on your LAN. That is the whole reason this repository exists — and it means the supported clients are Claude Desktop and Claude Code, not claude.ai in a browser.

If your appliance is internet-facing with a publicly-trusted certificate, you can skip the bridge and point any MCP client straight at the endpoint. See Install — any MCP client below.

---

Requirements

• A Netmon appliance with the MCP server enabled (Netmon 7.0.20 or newer).
• A user account with the API permission, and a personal access token carrying the mcp:* scopes you want the assistant to have.
• Claude Desktop for the .mcpb install. Claude Desktop supplies its own Node runtime, so nothing else is needed. Running the bridge outside Claude Desktop requires Node 18 or newer.

---

Install — Claude Desktop

1. Download netmon-mcp-<version>.mcpb from Releases. The same bundle ships with your appliance — Settings → System → Downloadables → Claude Desktop Extension.

2. In Claude Desktop, open Settings → Extensions → Advanced settings → Extension Developer → Install Extension… and select the file.

3. Fill in the two settings the extension asks for:

   Setting	Value
   Netmon URL	https://<your-netmon>/mcp — the full endpoint, including /mcp
   API Token	a personal access token (see below). The Bearer prefix is added for you if you leave it off.

4. Restart the extension. Ask Claude something like "list the devices that are down" to confirm it is working.

Minting a token

In Netmon, go to Settings → Users, click the key icon on your user, and create a personal access token. Select only the scopes the assistant needs — the token cannot be widened later, and it can be revoked from the same screen at any time.

The account must hold the API permission. Without it, token minting and OAuth consent are both refused.

---

Install — any MCP client

The appliance serves Streamable HTTP at https://<your-netmon>/mcp (POST for JSON-RPC, GET for the server-to-client SSE stream, DELETE to end a session).

Clients that support OAuth 2.1 discover the authorization server on their own: the endpoint answers an unauthenticated request with 401 and a WWW-Authenticate: Bearer resource_metadata="…" challenge pointing at RFC 9728 protected-resource metadata, alongside RFC 8414 authorization-server metadata and dynamic client registration at /auth/register. You sign in through your browser on your own Netmon and approve the scopes on a consent page.

Clients without OAuth support pass a token directly:

{
  "mcpServers": {
    "netmon": {
      "url": "https://netmon.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Claude Code and self-signed certificates

Most appliances serve a self-signed certificate. A direct type: http entry will fail against one — the OAuth bootstrap rejects the certificate and does not consult NODE_EXTRA_CA_CERTS. Use the bridge instead, which handles the certificate itself:

{
  "mcpServers": {
    "netmon": {
      "command": "node",
      "args": ["/path/to/netmon-mcpd/server/index.js"],
      "env": {
        "NETMON_URL": "https://netmon.example.com/mcp",
        "NETMON_TOKEN": "<your-token>"
      }
    }
  }
}

---

Tools

36 read tools, each wrapping a Netmon API endpoint and gated by an OAuth scope that is checked before the call runs.

Area	Scope	Example tools
Devices & fleet	mcp:devices	device_find, device_get, device_list, device_metric_summary, overwatch_summary, tags_list
Traffic & topology	mcp:vne, mcp:devices	top_bandwidth, netflow_search, netflow_raw_search, flow_summary, get_network_entity_info, arp_table, interfaces_search
Logs & security	mcp:logs	syslog_search, eventlog_search, eve_search, eve_get, log_severity_summary, syslog_facets
Alerts	mcp:alerts	alerts_list, alerts_history, maintenance_windows_list
Windows agent	mcp:devices	agent_processes, agent_services, agent_disk_usage
Live tools	mcp:tools, mcp:devices, mcp:capture	ping, traceroute, arp_lookup, port_map, snmp_test, snmp_walk_run, snmp_walk_last, search_ip, speedtest_history, capture_list, capture_get

All 36 tools

Tool	Title	What it answers
get_network_entity_info	Look Up WHOIS, GeoIP and DNS	Retrieves WHOIS, GeoIP and DNS information for a public IP address or hostname.
arp_lookup	ARP Lookup	Performs an ARP lookup to find the MAC address for a given Local IP address.
ping	Ping Host	Ping a target host from the Netmon server.
traceroute	Run Traceroute	Traceroute to a target from the Netmon server.
port_map	Scan Open Ports	Nmap port scan against a single host from the Netmon server.
search_ip	Search All Streams for an IP	Find every mention of a specific IP across Netmon's log and telemetry streams: syslog, Windows eventlog, Suricata EVE, aggregated NetFlow, and ARP.
syslog_search	Search Syslog	Search syslog messages from network devices.
eventlog_search	Search Windows Event Log	Search Windows Event Log entries ingested from Netmon agents.
eve_search	Search Suricata IDS Events	Search Suricata EVE-format IDS events.
eve_get	Get Suricata IDS Event	Fetch a single Suricata EVE event by id, decoded server-side.
log_severity_summary	Summarize Log Severities	Count log events grouped by severity over a time window.
syslog_facets	Syslog Facet Breakdown	Top-N value counts for ONE syslog field over a window — 'what are the top actions/reasons on this FortiGate in the last 2 hours' in a single call,...
netflow_search	Search Aggregated NetFlow	Search the FULL NetFlow history: the raw flow table (the last ~15 minutes) unioned with the aggregated rollup (4 weeks of history), windowed and pr...
netflow_raw_search	Search Raw NetFlow	Search raw NetFlow records (per-flow, not aggregated).
flow_summary	Summarize NetFlow Traffic	Summarize one host's network conversations: top peers, top ports, and a client-vs-service-side split, each with a residual "other" bucket plus over...
device_list	List Devices	List monitored devices.
device_get	Get Device Details	Fetch one device with its related state: tags, alerts, the ping / oid / interface / port / disk trackers configured on it, its SNMP walk trackers,...
device_find	Find Devices by Name or IP	Find devices matching a substring of label or ip_address.
overwatch_summary	Overwatch Health Summary	High-level network health snapshot for 'how's the network?' style questions.
snmp_test	Test SNMP Credentials	Probe a device for SNMP reachability using the Netmon snmptest binary.
snmp_walk_last	Get Cached SNMP Walk	Fetch the most recent stored SNMP walk for a device (cached in tools_walks).
snmp_walk_run	Run Fresh SNMP Walk	Trigger a FRESH SNMP walk against a device.
agent_services	List Windows Services	List Windows services on an agent-managed device — live read via the WMI tunnel.
agent_processes	List Windows Processes	List running processes on an agent-managed device — live read via the agent tunnel.
alerts_list	List Alert Definitions	List configured alert definitions across both axes of the rule engine.
alerts_history	Alert Incident History	Authoritative 'what fired and when' stream — wraps the alert_history table (one row per incident, both legacy and modern) and alert_outlet_log...
maintenance_windows_list	List Maintenance Windows	Lists maintenance windows — the suppression schedules that gate alert dispatch.
tags_list	List Tags	List tag definitions.
top_bandwidth	Top Bandwidth Talkers	Top NetFlow conversations over the last N minutes — the 'who's eating bandwidth right now?' question.
arp_table	Get ARP Table	Lists hosts observed on the local LAN(s) via the ARP table — the 'what devices have we seen recently?' question.
interfaces_search	Search Network Interfaces	Cross-device interface metadata listing — answers 'what interfaces are tracked across the fleet, named like X, on device Y?'.
device_metric_summary	Summarize Device Metrics	Day / week / month / all-time summary stats for a single device-tracker, by metric type.
agent_disk_usage	Browse Agent Disk Usage	Path-scoped folder-tree disk usage report from a Netmon agent — the 'D: drive is at 95%, what's eating it?' question.
capture_list	List Packet Captures	Read-only listing of packet captures.
capture_get	Get Packet Capture Status	Read-only single-capture detail.
speedtest_history	Speedtest History	Recent WAN speedtest results — answers 'is the internet healthy?'.

Eight scopes exist in total — the six above plus mcp:reports and mcp:system, which map to their permissions but have no tools yet.

---

Security model

Everything stays on your appliance. The bridge connects to the one URL you configure and nothing else. No telemetry, no vendor endpoint, no third-party service sits in the path. Netmon Services receives nothing.

Read-only. Every tool is a read. Netmon's agent write paths — killing a process, starting or stopping a Windows service, deleting a file, running PowerShell — are permanently excluded at the MCP layer, regardless of what the underlying token's permissions would otherwise allow. An assistant cannot change your monitoring configuration, acknowledge an alert, or act on a managed host.

Scoped. Each tool declares the OAuth scope it requires, and the scope is checked before the tool body runs. A token granted mcp:logs only cannot call device_list.

Yours, and no wider. A token acts as the user who minted it. Tag restrictions apply: an operator limited to the branch-offices tag gets an assistant limited to the same devices. The permission model is the one already governing the web interface and every other API client.

Revocable. Revoke a token from Settings → Users and the assistant loses access immediately. Tokens can also be scoped narrowly at mint time rather than revoked later.

Transport security

On first connection the bridge captures the appliance's TLS certificate and stores it at ~/.netmon-mcp/<hash-of-url>.pem, then verifies every later connection against that pinned certificate. This is trust-on-first-use: it protects against interception after the first connection, not during it. Make the first connection from a network you trust.

If you replace the appliance's certificate, delete the stale pin (rm ~/.netmon-mcp/*.pem) or the bridge will verify the new certificate against the old one and refuse to connect.

The bridge requires https://. Plain HTTP is rejected at startup.

---

Troubleshooting

The bridge writes a diagnostic log to ~/.netmon-mcp/wrapper.log.

Symptom	Cause
NETMON_URL must use https://	The URL is http://, or the scheme is missing.
TLS probe failed	The appliance is unreachable on 443 from this machine, or the hostname does not resolve.
Connects, then fails after a certificate change	Stale pin. Delete ~/.netmon-mcp/*.pem and reconnect.
Tools return an authorization error	The token lacks the scope that tool requires, or the account lacks the API permission.
No tools appear	The URL is missing the /mcp path.

---

Building

npm install
./build.sh            # or: ./build.sh 1.0.0 to stamp a version

Output lands in build/netmon-mcp-<version>.mcpb.

---

Privacy Policy

Full policy: https://netmon.com/privacy-policy/

What is collected. This bridge collects no data. It holds no account, no analytics, and no callback to Netmon Services. Two files are written locally, both under ~/.netmon-mcp/: the pinned certificate of the appliance you configured, and a diagnostic log of connection events. Your Netmon URL and token are supplied by you and are held only in the extension's own configuration.

How data is used and stored. Queries and results pass between your MCP client and your appliance. The bridge forwards messages and retains none of them. All monitoring data stays in the appliance's database, under your control, in your building.

Third-party sharing. None. The bridge contacts exactly one host — the appliance URL you configure. It sends nothing to Netmon Services or any other party.

Note that your MCP client is a separate product with its own policy. When you ask an assistant a question, the tool results it receives are handled by that client's vendor under their terms. Netmon does not control that leg, which is why the scopes on a token are worth setting narrowly.

Retention. Local files persist until you delete them: remove the extension, or rm -rf ~/.netmon-mcp. Revoking the token in Settings → Users ends access immediately. Retention of the monitoring data itself is configured on your appliance, by you.

Contact. [email protected]

---

Support

• Documentation: https://netmon.com/documentation/
• Issues with the bridge: GitHub Issues
• Everything else: [email protected]

License

Mozilla Public License 2.0 — see LICENSE.