Contents PDF

NetCrunch MCP Server

NetCrunch stellt seine REST API als MCP (Model Context Protocol) Server bereit. Dadurch können KI-Assistenten und LLM-basierte Tools die NetCrunch Management API programmgesteuert ermitteln und aufrufen.

Der MCP Server verwendet dieselben API-Schlüssel, Ratenbegrenzungen und Backend-Handler wie die REST API – jedes Tool entspricht 1:1 einem REST-Endpunkt.

Endpunkte

Der MCP Server unterstützt zwei Transportmechanismen. Beide sind unter dem Pfad /api/mcp verfügbar.

Transport	Methode	URL	Beschreibung
Streamable HTTP	`POST`	`/api/mcp`	Moderner Transport mit einem einzelnen Endpunkt (empfohlen)
SSE	`GET`	`/api/mcp/sse`	Öffnet einen Server-Sent-Events-Stream
SSE messages	`POST`	`/api/mcp/messages?sessionId=…`	Sendet JSON-RPC-Nachrichten an eine SSE-Sitzung

Streamable HTTP ist zustandslos – jede Anfrage erstellt eine neue MCP-Sitzung. Dies ist der einfachste Integrationsweg und funktioniert mit allen MCP-Clients.

SSE ist eine zustandsbehaftete Ausweichlösung für Clients, die eine dauerhafte Verbindung benötigen. Der Client öffnet zunächst /api/mcp/sse, um eine Sitzungs-ID zu erhalten, und sendet anschließend Anfragen an /api/mcp/messages?sessionId=<id>.

Authentifizierung

Jede Anfrage muss einen gültigen NetCrunch API-Schlüssel enthalten. Der MCP Server akzeptiert den Schlüssel an einem der folgenden Orte (in der angegebenen Reihenfolge geprüft):

Methode	Beispiel
`Authorization`-Header	`Authorization: Bearer YOUR_API_KEY`
`x-api-key`-Header	`x-api-key: YOUR_API_KEY`
Abfrageparameter	`?api_key=YOUR_API_KEY`

API-Schlüssel werden in der NetCrunch Administration Console unter User Profiles → API Keys erstellt. Der Schlüssel bestimmt, auf welche Knoten und Vorgänge der Aufrufer zugreifen kann – derselbe Sicherheitskontext gilt sowohl für MCP als auch für REST.

Anfragen ohne gültigen API-Schlüssel erhalten eine Fehlerantwort:


{ "error": "No API Key" }

Ratenbegrenzung

MCP-Anfragen verwenden denselben Token-Bucket pro API-Schlüssel wie die REST API. Standardlimits (konfigurierbar in server.cfg.yml):

Einstellung	Standard
Max requests per window	100
Window length	60 seconds

Wenn das Limit überschritten wird, geben Tool-Aufrufe ein Fehlerergebnis zurück. Nicht verwendete Token werden kontinuierlich aufgefüllt.

Client-Konfiguration

Claude Desktop

Fügen Sie Folgendes zu claude_desktop_config.json hinzu:


{
  "mcpServers": {
    "netcrunch": {
      "url": "https://YOUR_SERVER/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor / VS Code (Copilot)

Fügen Sie Folgendes zu den MCP-Einstellungen (.cursor/mcp.json oder VS Code MCP config) hinzu:


{
  "servers": {
    "netcrunch": {
      "url": "https://YOUR_SERVER/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Python (mcp client library)


from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async with streamablehttp_client(
    "https://YOUR_SERVER/api/mcp",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
    # List available tools
    tools = await session.list_tools()

    # Call a tool
    result = await session.call_tool("nodes.getProperties", {
        "node": "10.0.0.1",
        "properties": "Name,Address,OverallState"
    })
    print(result)

Verfügbare Tools

Der MCP Server stellt 50 Tools bereit, die in 8 Gruppen organisiert sind. Jedes Tool entspricht einem REST API-Endpunkt und akzeptiert dieselben Parameter. Erforderliche Parameter sind mit * gekennzeichnet.

Nodes (19 Tools)

Verwalten Sie überwachte Knoten – fügen Sie Knoten hinzu, löschen Sie sie, lesen und schreiben Sie Eigenschaften, steuern Sie die Überwachung und verwalten Sie Tags, Netzwerkdienste, Sensoren, benutzerdefinierte Felder und untergeordnete Knoten.

Tool	Beschreibung	Parameter
`nodes.add`	Einen neuen überwachten Knoten hinzufügen	networkAddress, name, type
`nodes.delete`	Einen überwachten Knoten löschen	node
`nodes.getProperties`	Knoteneigenschaften abrufen	node, properties
`nodes.getProperty`	Eine einzelne Knoteneigenschaft abrufen	node, property*
`nodes.setProperties`	Mehrere Knoteneigenschaften festlegen	node
`nodes.setProperty`	Eine einzelne Knoteneigenschaft festlegen	node, property*
`nodes.setMonitoring`	Überwachung aktivieren oder deaktivieren	node, value* (on/off), disabledFrom, disabledUntil, reset
`nodes.addNetworkService`	Einen Netzwerkdienstmonitor hinzufügen	node, name*, protocolId, timeout, repeat, additionalRepeat, monitoringTime, overrideSuppressing, param
`nodes.setNetworkServiceParams`	Parameter des Dienstmonitors aktualisieren	node, service*, protocolId, timeout, repeat, additionalRepeat, monitoringTime, overrideSuppressing
`nodes.deleteNetworkService`	Einen Dienstmonitor entfernen	node, service*
`nodes.setSensorParams`	Sensorüberwachung konfigurieren	node, sensor*, enabled, monitoringTime, credentials
`nodes.setMonitoringEngineParams`	Monitoring Engine konfigurieren	node, engine*, enabled, monitoringTime, credentials
`nodes.setCustomFieldValue`	Einen Wert für ein benutzerdefiniertes Feld festlegen	node, field*, value
`nodes.deleteCustomField`	Ein benutzerdefiniertes Feld löschen	node, field*
`nodes.addChild`	Einen untergeordneten Knoten hinzufügen	node, child*
`nodes.deleteChild`	Einen untergeordneten Knoten entfernen	node, child*
`nodes.addTag`	Ein Tag hinzufügen	node, tag*
`nodes.deleteTag`	Ein Tag entfernen	node, tag*
`nodes.removeTags`	Alle Tags entfernen	node

Der Parameter node akzeptiert eine Knoten-ID (numerisch), einen Namen, eine IP-Adresse oder einen DNS-Namen.

Views (9 Tools)

Verwalten Sie Netzwerkansichten und Ansichtsordner.

Tool	Beschreibung	Parameter
`views.add`	Eine neue Ansicht erstellen	name*, parent
`views.addFolder`	Einen neuen Ordner erstellen	name*, parent
`views.delete`	Eine Ansicht löschen	map
`views.getProperties`	Ansichtseigenschaften abrufen	map, properties
`views.getProperty`	Eine einzelne Eigenschaft abrufen	map, property*
`views.setProperties`	Mehrere Eigenschaften festlegen	map
`views.setProperty`	Eine einzelne Eigenschaft festlegen	map, property*
`views.addNode`	Einen Knoten zu einer Ansicht hinzufügen	map, node*
`views.removeNode`	Einen Knoten aus einer Ansicht entfernen	map, node*

Der Parameter map akzeptiert eine Ansichts-ID, einen Namen oder einen Pfad.

Policies (6 Tools)

Verwalten Sie Überwachungsrichtlinien.

Tool	Beschreibung	Parameter
`policies.getProperties`	Richtlinieneigenschaften abrufen	map, properties
`policies.getProperty`	Eine einzelne Eigenschaft abrufen	map, property*
`policies.setProperties`	Mehrere Eigenschaften festlegen	map
`policies.setProperty`	Eine einzelne Eigenschaft festlegen	map, property*
`policies.addNode`	Einen Knoten zu einer Richtlinie hinzufügen	map, node*
`policies.removeNode`	Einen Knoten aus einer Richtlinie entfernen	map, node*

Notes (5 Tools)

Verwalten Sie Knoten zugeordnete Notizen.

Tool	Beschreibung	Parameter
`notes.add`	Eine Notiz zu einem Knoten hinzufügen	node, subject, text, label (red/green/blue/yellow), due, refid, category, archived
`notes.get`	Eine Notiz anhand der Referenz-ID abrufen	node, refid*
`notes.getProperty`	Eine einzelne Notizeigenschaft abrufen	node, refid, property
`notes.update`	Eine Notiz aktualisieren	node, refid*, subject, text, label, due, category, archived
`notes.updateProperty`	Eine einzelne Notizeigenschaft aktualisieren	node, refid, property

Interface Settings (5 Tools)

Verwalten Sie die Anzeigeeinstellungen von Netzwerkschnittstellen.

Tool	Beschreibung	Parameter
`interfaceSettings.set`	Schnittstelleneinstellungen festlegen	node, ifIndex*, name, speed, note
`interfaceSettings.get`	Schnittstelleneinstellungen abrufen	node, ifIndex
`interfaceSettings.getAll`	Alle Schnittstellen abrufen	node
`interfaceSettings.delete`	Schnittstelleneinstellungen löschen	node, ifIndex
`interfaceSettings.deleteAll`	Alle Schnittstelleneinstellungen löschen	node

Credentials (2 Tools)

Listen Sie Anmeldeinformationstypen und -profile auf (nur für Administratoren).

Tool	Beschreibung	Parameter
`credentials.getTypes`	Anmeldeinformationstypen auflisten	—
`credentials.get`	Anmeldeinformationen nach Typ abrufen	type*

IP SLA (2 Tools)

Tool	Beschreibung	Parameter
`ipsla.get`	Alle IP SLA-Vorgänge auflisten	—
`ipsla.getNode`	IP SLA für einen Knoten abrufen	node

NQA (2 Tools)

Tool	Beschreibung	Parameter
`nqa.get`	Alle NQA-Vorgänge auflisten	—
`nqa.getNode`	NQA für einen Knoten abrufen	node

Beispielgespräche

Nach der Verbindung kann ein KI-Assistent NetCrunch Tools ganz natürlich verwenden:

Benutzer: Zeige mir die Eigenschaften des Knotens unter 10.0.0.1

Assistent ruft nodes.getProperties mit { "node": "10.0.0.1" } auf und gibt das Ergebnis zurück.

Benutzer: Deaktiviere die Überwachung des Webservers für die nächsten 2 Stunden

Assistent ruft nodes.setMonitoring mit { "node": "web-server", "value": "off", "disabledUntil": "2026-04-26T20:00:00Z" } auf.

Benutzer: Füge Knoten 42 eine Notiz hinzu, dass die Firmware aktualisiert wurde

Assistent ruft notes.add mit { "node": "42", "subject": "Firmware updated", "text": "Firmware was updated to latest version.", "label": "green" } auf.

Fehlerbehandlung

Fehler bei Tool-Aufrufen werden als MCP-Fehlerergebnisse mit isError: true und einem JSON-Textinhaltsblock zurückgegeben:


{
  "content": [{ "type": "text", "text": "{\"error\":\"Authentication Failed\"}" }],
  "isError": true
}

Häufige Fehlerbedingungen:

Fehler	Ursache
`No API Key`	Der Anfrage fehlt die Authentifizierung
`Authentication Failed`	Ungültiger oder abgelaufener API-Schlüssel
`Node not Found`	Der angegebene Knoten ist nicht vorhanden
`Access Denied`	Der API-Schlüssel verfügt nicht über die Berechtigung für diesen Vorgang
`Too Many Requests`	Ratenlimit überschritten – warten Sie und versuchen Sie es erneut

agentaiapiautomationintegrationsmcprest