Contents PDF

Serwer MCP NetCrunch

NetCrunch udostępnia swój interfejs REST API jako serwer MCP (Model Context Protocol), umożliwiając asystentom AI i narzędziom opartym na LLM programowe wykrywanie i wywoływanie interfejsu zarządzania NetCrunch.

Serwer MCP współdzieli z REST API te same klucze API, limity liczby żądań i moduły obsługi zaplecza — każde narzędzie odpowiada dokładnie jednemu punktowi końcowemu REST.

Punkty końcowe

Serwer MCP obsługuje dwa mechanizmy transportu. Oba są dostępne pod ścieżką /api/mcp.

Mechanizm transportu	Metoda	URL	Opis
Streamable HTTP	`POST`	`/api/mcp`	Nowoczesny transport z pojedynczym punktem końcowym (zalecany)
SSE	`GET`	`/api/mcp/sse`	Otwiera strumień Server-Sent Events
Wiadomości SSE	`POST`	`/api/mcp/messages?sessionId=…`	Wysyła wiadomości JSON-RPC do sesji SSE

Streamable HTTP jest bezstanowy — każde żądanie tworzy nową sesję MCP. Jest to najprostszy sposób integracji i działa ze wszystkimi klientami MCP.

SSE to stanowy mechanizm awaryjny dla klientów wymagających stałego połączenia. Klient najpierw otwiera /api/mcp/sse, aby uzyskać identyfikator sesji, a następnie wysyła żądania do /api/mcp/messages?sessionId=<id>.

Uwierzytelnianie

Każde żądanie musi zawierać prawidłowy klucz API NetCrunch. Serwer MCP akceptuje klucz w jednej z poniższych lokalizacji (sprawdzanych w podanej kolejności):

Metoda	Przykład
Nagłówek `Authorization`	`Authorization: Bearer YOUR_API_KEY`
Nagłówek `x-api-key`	`x-api-key: YOUR_API_KEY`
Parametr zapytania	`?api_key=YOUR_API_KEY`

Klucze API są tworzone w NetCrunch Administration Console w sekcji User Profiles → API Keys. Klucz określa, do których węzłów i operacji wywołujący ma dostęp — ten sam kontekst zabezpieczeń ma zastosowanie zarówno do MCP, jak i REST.

Żądania bez prawidłowego klucza API otrzymują odpowiedź błędu:


{ "error": "No API Key" }

Ograniczanie liczby żądań

Żądania MCP korzystają z tego samego zasobnika tokenów dla każdego klucza API co REST API. Domyślne limity (konfigurowane w server.cfg.yml):

Ustawienie	Wartość domyślna
Maksymalna liczba żądań w oknie	100
Długość okna	60 sekund

Po przekroczeniu limitu wywołania narzędzi zwracają wynik błędu. Niewykorzystane tokeny są uzupełniane w sposób ciągły.

Konfiguracja klienta

Claude Desktop

Dodaj do pliku claude_desktop_config.json:


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

Cursor / VS Code (Copilot)

Dodaj do ustawień MCP (.cursor/mcp.json lub konfiguracji MCP VS Code):


{
  "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)

Dostępne narzędzia

Serwer MCP udostępnia 50 narzędzi zorganizowanych w 8 grup. Każde narzędzie odpowiada punktowi końcowemu REST API i przyjmuje te same parametry. Wymagane parametry są oznaczone symbolem *.

Węzły (19 narzędzi)

Zarządzanie monitorowanymi węzłami — dodawanie, usuwanie, odczytywanie i zapisywanie właściwości, sterowanie monitoringiem, zarządzanie tagami, usługami sieciowymi, sensorami, polami niestandardowymi i węzłami podrzędnymi.

Narzędzie	Opis	Parametry
`nodes.add`	Dodaj nowy monitorowany węzeł	networkAddress, name, type
`nodes.delete`	Usuń monitorowany węzeł	node
`nodes.getProperties`	Pobierz właściwości węzła	node, properties
`nodes.getProperty`	Pobierz pojedynczą właściwość węzła	node, property*
`nodes.setProperties`	Ustaw wiele właściwości węzła	node
`nodes.setProperty`	Ustaw pojedynczą właściwość węzła	node, property*
`nodes.setMonitoring`	Włącz lub wyłącz monitoring	node, value* (on/off), disabledFrom, disabledUntil, reset
`nodes.addNetworkService`	Dodaj monitor usługi sieciowej	node, name*, protocolId, timeout, repeat, additionalRepeat, monitoringTime, overrideSuppressing, param
`nodes.setNetworkServiceParams`	Zaktualizuj parametry monitora usługi	node, service*, protocolId, timeout, repeat, additionalRepeat, monitoringTime, overrideSuppressing
`nodes.deleteNetworkService`	Usuń monitor usługi	node, service*
`nodes.setSensorParams`	Skonfiguruj monitoring sensora	node, sensor*, enabled, monitoringTime, credentials
`nodes.setMonitoringEngineParams`	Skonfiguruj silnik monitoringu	node, engine*, enabled, monitoringTime, credentials
`nodes.setCustomFieldValue`	Ustaw wartość pola niestandardowego	node, field*, value
`nodes.deleteCustomField`	Usuń pole niestandardowe	node, field*
`nodes.addChild`	Dodaj węzeł podrzędny	node, child*
`nodes.deleteChild`	Usuń węzeł podrzędny	node, child*
`nodes.addTag`	Dodaj tag	node, tag*
`nodes.deleteTag`	Usuń tag	node, tag*
`nodes.removeTags`	Usuń wszystkie tagi	node

Parametr node akceptuje identyfikator węzła (numeryczny), nazwę, adres IP lub nazwę DNS.

Widoki (9 narzędzi)

Zarządzanie widokami sieci i folderami widoków.

Narzędzie	Opis	Parametry
`views.add`	Utwórz nowy widok	name*, parent
`views.addFolder`	Utwórz nowy folder	name*, parent
`views.delete`	Usuń widok	map
`views.getProperties`	Pobierz właściwości widoku	map, properties
`views.getProperty`	Pobierz pojedynczą właściwość	map, property*
`views.setProperties`	Ustaw wiele właściwości	map
`views.setProperty`	Ustaw pojedynczą właściwość	map, property*
`views.addNode`	Dodaj węzeł do widoku	map, node*
`views.removeNode`	Usuń węzeł z widoku	map, node*

Parametr map akceptuje identyfikator widoku, nazwę lub ścieżkę.

Zasady (6 narzędzi)

Zarządzanie zasadami monitoringu.

Narzędzie	Opis	Parametry
`policies.getProperties`	Pobierz właściwości zasady	map, properties
`policies.getProperty`	Pobierz pojedynczą właściwość	map, property*
`policies.setProperties`	Ustaw wiele właściwości	map
`policies.setProperty`	Ustaw pojedynczą właściwość	map, property*
`policies.addNode`	Dodaj węzeł do zasady	map, node*
`policies.removeNode`	Usuń węzeł z zasady	map, node*

Notatki (5 narzędzi)

Zarządzanie notatkami dołączonymi do węzłów.

Narzędzie	Opis	Parametry
`notes.add`	Dodaj notatkę do węzła	node, subject, text, label (red/green/blue/yellow), due, refid, category, archived
`notes.get`	Pobierz notatkę według identyfikatora referencyjnego	node, refid*
`notes.getProperty`	Pobierz pojedynczą właściwość notatki	node, refid, property
`notes.update`	Zaktualizuj notatkę	node, refid*, subject, text, label, due, category, archived
`notes.updateProperty`	Zaktualizuj pojedynczą właściwość notatki	node, refid, property

Ustawienia interfejsów (5 narzędzi)

Zarządzanie ustawieniami wyświetlania interfejsów sieciowych.

Narzędzie	Opis	Parametry
`interfaceSettings.set`	Ustaw ustawienia interfejsu	node, ifIndex*, name, speed, note
`interfaceSettings.get`	Pobierz ustawienia interfejsu	node, ifIndex
`interfaceSettings.getAll`	Pobierz wszystkie interfejsy	node
`interfaceSettings.delete`	Usuń ustawienia interfejsu	node, ifIndex
`interfaceSettings.deleteAll`	Usuń wszystkie ustawienia interfejsów	node

Dane uwierzytelniające (2 narzędzia)

Wyświetlanie typów i profili danych uwierzytelniających (tylko administrator).

Narzędzie	Opis	Parametry
`credentials.getTypes`	Wyświetl typy danych uwierzytelniających	—
`credentials.get`	Pobierz dane uwierzytelniające według typu	type*

IP SLA (2 narzędzia)

Narzędzie	Opis	Parametry
`ipsla.get`	Wyświetl wszystkie operacje IP SLA	—
`ipsla.getNode`	Pobierz IP SLA dla węzła	node

NQA (2 narzędzia)

Narzędzie	Opis	Parametry
`nqa.get`	Wyświetl wszystkie operacje NQA	—
`nqa.getNode`	Pobierz NQA dla węzła	node

Przykładowe rozmowy

Po nawiązaniu połączenia asystent AI może korzystać z narzędzi NetCrunch w naturalny sposób:

Użytkownik: Pokaż właściwości węzła pod adresem 10.0.0.1

Asystent wywołuje nodes.getProperties z { "node": "10.0.0.1" } i zwraca wynik.

Użytkownik: Wyłącz monitoring serwera WWW na następne 2 godziny

Asystent wywołuje nodes.setMonitoring z { "node": "web-server", "value": "off", "disabledUntil": "2026-04-26T20:00:00Z" }.

Użytkownik: Dodaj do węzła 42 notatkę informującą, że oprogramowanie układowe zostało zaktualizowane

Asystent wywołuje notes.add z { "node": "42", "subject": "Firmware updated", "text": "Firmware was updated to latest version.", "label": "green" }.

Obsługa błędów

Błędy wywołań narzędzi są zwracane jako wyniki błędów MCP z wartością isError: true oraz blokiem treści tekstowej JSON:


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

Typowe warunki błędów:

Błąd	Przyczyna
`No API Key`	W żądaniu brakuje uwierzytelniania
`Authentication Failed`	Nieprawidłowy lub wygasły klucz API
`Node not Found`	Określony węzeł nie istnieje
`Access Denied`	Klucz API nie ma uprawnień do wykonania tej operacji
`Too Many Requests`	Przekroczono limit liczby żądań — odczekaj i spróbuj ponownie

agentaiapiautomationintegrationsmcprest