Contents PDF

NetCrunch MCP Server

NetCrunch exposes its REST API as an MCP (Model Context Protocol) server, allowing AI assistants and LLM-based tools to discover and call the NetCrunch management API programmatically.

The MCP server shares the same API keys, rate limits, and backend handlers as the REST API — every tool maps 1-to-1 to a REST endpoint.

Endpoints

The MCP server supports two transports. Both are available at the /api/mcp path.

Transport	Method	URL	Description
Streamable HTTP	`POST`	`/api/mcp`	Modern single-endpoint transport (recommended)
SSE	`GET`	`/api/mcp/sse`	Opens a Server-Sent Events stream
SSE messages	`POST`	`/api/mcp/messages?sessionId=…`	Sends JSON-RPC messages to an SSE session

Streamable HTTP is stateless — each request creates a fresh MCP session. This is the simplest integration path and works with all MCP clients.

SSE is a stateful fallback for clients that require a persistent connection. The client first opens /api/mcp/sse to get a session ID, then sends requests to /api/mcp/messages?sessionId=<id>.

Authentication

Every request must include a valid NetCrunch API key. The MCP server accepts the key in any of these locations (checked in order):

Method	Example
`Authorization` header	`Authorization: Bearer YOUR_API_KEY`
`x-api-key` header	`x-api-key: YOUR_API_KEY`
Query parameter	`?api_key=YOUR_API_KEY`

API keys are created in the NetCrunch Administration Console under User Profiles → API Keys. The key determines which nodes and operations the caller can access — the same security context applies to both MCP and REST.

Requests without a valid API key receive an error response:


{ "error": "No API Key" }

Rate Limiting

MCP requests share the same per-API-key token bucket as the REST API. Default limits (configurable in server.cfg.yml):

Setting	Default
Max requests per window	100
Window length	60 seconds

When the limit is exceeded, tool calls return an error result. Unused tokens refill continuously.

Client Configuration

Claude Desktop

Add to claude_desktop_config.json:


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

Cursor / VS Code (Copilot)

Add to MCP settings (.cursor/mcp.json or VS Code MCP config):


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

Available Tools

The MCP server exposes 50 tools organized into 8 groups. Each tool corresponds to a REST API endpoint and accepts the same parameters. Required parameters are marked with *.

Nodes (19 tools)

Manage monitored nodes — add, delete, read/write properties, control monitoring, manage tags, network services, sensors, custom fields, and child nodes.

Tool	Description	Parameters
`nodes.add`	Add a new monitored node	networkAddress, name, type
`nodes.delete`	Delete a monitored node	node
`nodes.getProperties`	Get node properties	node, properties
`nodes.getProperty`	Get a single node property	node, property*
`nodes.setProperties`	Set multiple node properties	node
`nodes.setProperty`	Set a single node property	node, property*
`nodes.setMonitoring`	Enable or disable monitoring	node, value* (on/off), disabledFrom, disabledUntil, reset
`nodes.addNetworkService`	Add a network service monitor	node, name*, protocolId, timeout, repeat, additionalRepeat, monitoringTime, overrideSuppressing, param
`nodes.setNetworkServiceParams`	Update service monitor params	node, service*, protocolId, timeout, repeat, additionalRepeat, monitoringTime, overrideSuppressing
`nodes.deleteNetworkService`	Remove a service monitor	node, service*
`nodes.setSensorParams`	Configure sensor monitoring	node, sensor*, enabled, monitoringTime, credentials
`nodes.setMonitoringEngineParams`	Configure monitoring engine	node, engine*, enabled, monitoringTime, credentials
`nodes.setCustomFieldValue`	Set a custom field value	node, field*, value
`nodes.deleteCustomField`	Delete a custom field	node, field*
`nodes.addChild`	Add a child node	node, child*
`nodes.deleteChild`	Remove a child node	node, child*
`nodes.addTag`	Add a tag	node, tag*
`nodes.deleteTag`	Remove a tag	node, tag*
`nodes.removeTags`	Remove all tags	node

The node parameter accepts a node ID (numeric), name, IP address, or DNS name.

Views (9 tools)

Manage network views and view folders.

Tool	Description	Parameters
`views.add`	Create a new view	name*, parent
`views.addFolder`	Create a new folder	name*, parent
`views.delete`	Delete a view	map
`views.getProperties`	Get view properties	map, properties
`views.getProperty`	Get a single property	map, property*
`views.setProperties`	Set multiple properties	map
`views.setProperty`	Set a single property	map, property*
`views.addNode`	Add a node to a view	map, node*
`views.removeNode`	Remove a node from a view	map, node*

The map parameter accepts a view ID, name, or path.

Policies (6 tools)

Manage monitoring policies.

Tool	Description	Parameters
`policies.getProperties`	Get policy properties	map, properties
`policies.getProperty`	Get a single property	map, property*
`policies.setProperties`	Set multiple properties	map
`policies.setProperty`	Set a single property	map, property*
`policies.addNode`	Add a node to a policy	map, node*
`policies.removeNode`	Remove a node from a policy	map, node*

Notes (5 tools)

Manage notes attached to nodes.

Tool	Description	Parameters
`notes.add`	Add a note to a node	node, subject, text, label (red/green/blue/yellow), due, refid, category, archived
`notes.get`	Get a note by reference ID	node, refid*
`notes.getProperty`	Get a single note property	node, refid, property
`notes.update`	Update a note	node, refid*, subject, text, label, due, category, archived
`notes.updateProperty`	Update a single note property	node, refid, property

Interface Settings (5 tools)

Manage network interface display settings.

Tool	Description	Parameters
`interfaceSettings.set`	Set interface settings	node, ifIndex*, name, speed, note
`interfaceSettings.get`	Get interface settings	node, ifIndex
`interfaceSettings.getAll`	Get all interfaces	node
`interfaceSettings.delete`	Delete interface settings	node, ifIndex
`interfaceSettings.deleteAll`	Delete all interface settings	node

Credentials (2 tools)

List credential types and profiles (admin only).

Tool	Description	Parameters
`credentials.getTypes`	List credential types	—
`credentials.get`	Get credentials by type	type*

IP SLA (2 tools)

Tool	Description	Parameters
`ipsla.get`	List all IP SLA operations	—
`ipsla.getNode`	Get IP SLA for a node	node

NQA (2 tools)

Tool	Description	Parameters
`nqa.get`	List all NQA operations	—
`nqa.getNode`	Get NQA for a node	node

Example Conversations

Once connected, an AI assistant can use NetCrunch tools naturally:

User: Show me the properties of the node at 10.0.0.1

Assistant calls nodes.getProperties with { "node": "10.0.0.1" } and returns the result.

User: Disable monitoring on the web server for the next 2 hours

Assistant calls nodes.setMonitoring with { "node": "web-server", "value": "off", "disabledUntil": "2026-04-26T20:00:00Z" }.

User: Add a note to node 42 saying the firmware was updated

Assistant calls notes.add with { "node": "42", "subject": "Firmware updated", "text": "Firmware was updated to latest version.", "label": "green" }.

Error Handling

Tool call errors are returned as MCP error results with isError: true and a JSON text content block:


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

Common error conditions:

Error	Cause
`No API Key`	Request missing authentication
`Authentication Failed`	Invalid or expired API key
`Node not Found`	The specified node does not exist
`Access Denied`	API key lacks permission for this operation
`Too Many Requests`	Rate limit exceeded — wait and retry

agentaiapiautomationintegrationsmcprest