IPNetwork MCP API Reference Manual

Overview

The IPNetwork MCP (Model Context Protocol) service provides a comprehensive API for managing network monitoring infrastructure. It allows you to create, configure, and monitor hosts, monitors, alerts, credentials, schedules, and other network monitoring components.

General Information

The first version of the MCP API is only available over the HTTPS protocol as an experimental feature. By default, it is disabled. For management, a new MCP page has been implemented in the settings dialog.

Enable MCP controls the startup of the MCP server. Port sets the port on which the MCP server listens. MCP binding address sets the address on which the server listens. By default, 0.0.0.0 is used, allowing connections from any address. If you need to limit MCP use to only one host, you can specify 127.0.0.1 as the address.

For using MCP, clients must specify the correct token. The token value can be copied from the MCP settings page. There are two tokens — one (read-write) provides full access, the other (read-only) provides access only to read functions, not changing the state of IPNetwork Monitor. If desired (e.g., in case of leakage), tokens can be regenerated.

Authentication

The MCP service uses token-based authentication. All API requests must include a valid authentication token.

Token Types

Obtaining Tokens

1. Open IPNetwork Monitor settings dialog
2. Navigate to the MCP settings page
3. Copy the appropriate token (read-write or read-only)

Token Security

• Never share read-write tokens with untrusted parties
• Regenerate tokens immediately if you suspect they have been compromised
• Use read-only tokens for integrations that only need to query data
• Tokens can be regenerated from the MCP settings page at any time

Functions by Access Level

Read-Only Token Functions:

• All list-* functions (list-agents, list-alerts, list-hosts, etc.)
• All get-* functions (get-host, get-monitor, get-alert, etc.)
• settings and effective-settings
• monitor-state
• list-children
• get-parent

Read-Write Token Functions (in addition to read-only):

• All create-* functions (create-host, create-monitor, create-alert, etc.)

Table of Contents

1. Core Concepts
2. Credentials Management
3. Host and Host Group Management
4. Monitor Management
5. Alerting System
6. Schedules
7. Actions
8. Settings and Configuration
9. Monitoring and State
10. Reference Tables
11. Error Handling
12. Troubleshooting
13. Glossary

Core Concepts

Object Hierarchy

The IPNetwork system follows a hierarchical structure:

Root
└── Agent
    └── Host Group
        └── Host
            └── Application (optional)
                └── Monitor

Object Types

• Root: Top-level configuration
• Agent: Monitoring agent instance (see List Agents)
• Host Group: Logical grouping of hosts (see Host Groups)
• Host: Network device or server being monitored (see Hosts)
• Application: Application-level grouping (optional)
• Monitor: Specific monitoring check (see Monitor Management and Monitor Types)

Settings Inheritance

Universal (non-type-specific) settings can be inherited from parent objects. Each object type can have its own settings that may override or inherit from parent configurations. See Settings and Configuration for details on available settings, and Get Effective Settings to retrieve resolved settings with inheritance applied.

Notes on object creation

Note: If an object with the given name already exists, the name of the newly created object will be modified: “New monitor” -> “New monitor #2” etc.

Note: If a parameter represents a reference to another object, then its value can be specified either as a number (identifier) or as a string (in which case this is the name of the object).

Note: If the source data is inconsistent, then, as a rule, the object is still created, but incorrect data is ignored (with the output of a warning message in the errors field).

Credentials Management

Unix-like Credentials

Create and manage Unix/Linux credentials for SSH and other Unix-based monitoring. These credentials can be assigned to hosts and monitors via the credentials.unix setting (see Settings and Configuration).

Create Unix Credentials

Function: create-unix-credentials

Parameters:

• name (string): Name of the credentials set to be created
• config (object): Credentials parameters:
  • user (string): Unix user name
  • password (string): Password (unencrypted!)

Result (on successful execution): Identifier of the created credentials (field id) + messages about ignored errors in the source data (field errors)

Request Example:

{
  "name": "Linux Server Access",
  "config": {
    "user": "monitor",
    "password": "secure_password"
  }
}

Response Example:

{
  "id": 5,
  "errors": []
}

Get Unix Credentials

Function: get-unix-credentials

Parameters:

• id (number): ID of the credentials set

Result (on successful execution): Settings of the credentials (caution – contains password in the form of unencrypted text!) in the config field. In addition, the name of the credentials is output in the name field.

Response Example:

{
  "name": "New Unix User",
  "config": {
    "password": "pass sword",
    "user": "luser"
  }
}

List Unix Credentials

Function: list-unix-credentials

Parameters: absent

Result (on successful execution): List of known Unix-type credentials in the credentials field

Response Example:

{
  "credentials": [
    {"id": 0, "name": "Default Unix-like Credentials"},
    {"id": 8, "name": "UNIX-like Credentials for FTP on 192.168.14.102"}
  ]
}

Windows Credentials

Create and manage Windows credentials for Windows-based monitoring (WMI monitors, etc.). These credentials can be assigned via the credentials.windows setting (see Settings and Configuration).

Create Windows Credentials

Function: create-windows-credentials

Parameters:

• name (string): Name of the credentials set to be created
• config (object): Credentials parameters:
  • domain (string): Windows domain
  • user (string): Windows user name
  • password (string): Password (unencrypted!)

Result (on successful execution): Identifier of the created credentials (field id) + messages about ignored errors in the source data (field errors)

Request Example:

{
  "name": "Windows Domain Access",
  "config": {
    "domain": "CORP",
    "user": "monitor",
    "password": "secure_password"
  }
}

Response Example:

{
  "id": 3,
  "errors": []
}

Get Windows Credentials

Function: get-windows-credentials

Parameters:

• id (number): ID of the credentials set

Result (on successful execution): Settings of the credentials (caution – contains password in the form of unencrypted text!) in the config field. In addition, the name of the credentials is output in the name field.

Response Example:

{
  "name": "New Windows User",
  "config": {
    "domain": "evil",
    "password": "pass sword",
    "user": "luser"
  }
}

List Windows Credentials

Function: list-windows-credentials

Parameters: absent

Result (on successful execution): List of known Windows-type credentials in the credentials field

Response Example:

{
  "credentials": [
    {"id": 0, "name": "Default Windows Credentials"},
    {"id": 8, "name": "Windows Credentials for Administrator on 192.168.14.103"}
  ]
}

SNMP Credentials

Create and manage SNMP credentials for SNMP-based monitoring. These credentials can be assigned via the credentials.snmp setting (see Settings and Configuration).

Create SNMP Credentials

Function: create-snmp-credentials

Parameters:

• name (string): Name of the credentials set to be created
• config (object): Credentials parameters:
  • version (number): SNMP version – 1, 2 (for v2c), 3
  • community (string): Community name (for v1/v2c)
  • security (object, optional): Access parameters (for v3). Contains the following fields:
    • auth (string): Authentication algorithm. Supported values: none, md5, sha1
    • user (string, optional): User name (if auth != none)
    • password (string, optional): User password (if auth != none)
    • priv (string, optional): Privacy protection algorithm. Supported values: none, des, aes
    • key (string, optional): Encryption key for the privacy protection algorithm (if priv != none)

Result (on successful execution): Identifier of the created credentials (field id) + messages about ignored errors in the source data (field errors)

Request Example (SNMP v2c):

{
  "name": "SNMP v2 Community",
  "config": {
    "version": 2,
    "community": "public"
  }
}

Request Example (SNMP v3):

{
  "name": "SNMPv3",
  "config": {
    "version": 3,
    "community": "public",
    "security": {
      "auth": "md5",
      "key": "b66f4e61bffda0bee827e2072ac55fb865c474e874d89da9",
      "password": "pass sword",
      "priv": "des",
      "user": "$AdminName"
    }
  }
}

Response Example:

{
  "id": 7,
  "errors": []
}

Get SNMP Credentials

Function: get-snmp-credentials

Parameters:

• id (number): ID of the credentials set

Result (on successful execution): Settings of the credentials (caution – may contain password in the form of unencrypted text!) in the config field. In addition, the name of the credentials is output in the name field.

Response Example:

{
  "name": "SNMPv3",
  "config": {
    "community": "public",
    "security": {
      "auth": "md5",
      "key": "b66f4e61bffda0bee827e2072ac55fb865c474e874d89da9",
      "password": "pass sword",
      "priv": "des",
      "user": "$AdminName"
    },
    "version": 3
  }
}

List SNMP Credentials

Function: list-snmp-credentials

Parameters: absent

Result (on successful execution): List of known SNMP-type credentials in the credentials field

Response Example:

{
  "credentials": [
    {"id": 0, "name": "Default SNMP Credentials"},
    {"id": 2, "name": "SNMPv3 Credentials 192.168.14.104"}
  ]
}

Host and Host Group Management

Host Groups

Host groups provide logical organization of hosts and can inherit settings to child objects. Host groups can be nested, i.e., one host group can contain other host groups. See Host Group Kinds for valid kind values and Host Icon Files for available icon options.

Create Host Group

Function: create-hostgroup

Parameters:

• parentType (string): Type of parent object ("hostgroup" or "agent")
• parentId (number): ID of the parent object
• name (string): Name of the host group
• config (object):
• kind (string): Host group kind/type. Valid values (case-sensitive; values separated by slash are equivalent):
  • "server": Server group
  • "net": Network equipment group
  • "desktop"/"notebook": Desktop/notebook group
  • "printer"/"ups": Printer/UPS group
  • "misc": Miscellaneous group
• defaultHostIcon (string, optional): Default icon filename for hosts in this group
• settings (object, optional): Universal settings for this host group

Result (on successful execution): Identifier of the created host group (field id) + messages about ignored errors in the source data (field errors)

Request Example:

{
  "parentType": "agent",
  "parentId": 1,
  "name": "Production Servers",
  "config": {
    "kind": "server",
    "defaultHostIcon": "server.png"
  }
}

Response Example:

{
  "id": 12,
  "errors": []
}

Get Host Group

Function: get-hostgroup

Parameters:

• id (number): ID of the host group

Result (on successful execution): Specific settings for the host group in the config field. In addition, the host group name is output in the name field.

Response Example:

{
  "name": "Network Equipment",
  "config": {
    "defaultHostIcon": "OS/Windows.png",
    "kind": "net"
  }
}

List Children

Function: list-children

Lists child objects (host groups, hosts, applications, monitors) of a parent.

Parameters:

• type (string): Type of parent ("agent", "hostgroup", "host", or "application")
• id (number): ID of the parent object
• plain (boolean, optional): If true, shows nested structure flattened (default: false)

Result (on successful execution): List of child objects (identifier, name) in the corresponding output field. For monitors, the monitor type is also added.

Note: “Plain” view of the tree means that from nested host groups and applications are removed from the tree. All host groups are considered to belong directly to the agent, all monitors are considered to belong directly to the host.

Response Example:

{
  "applications": [
    {"id": 55, "name": "Cool App"},
    {"id": 75, "name": "Cooler App"}
  ],
  "monitors": [
    {"id": 568, "name": "Non-standard ping", "type": "PING"},
    {"id": 1234, "name": "Real-world DB", "type": "MySQL Database"}
  ]
}

Hosts

Hosts represent network devices or servers being monitored. Hosts must be created within a host group. See Host Icon Files for available icon options and Schedules for maintenance schedule configuration.

Create Host

Function: create-host

Parameters:

• parentId (number): ID of the parent host group
• name (string): Host name
• config (object):
• hostIcon (string, optional): Host icon filename
• hostDef (object): Host definition (mutually exclusive options):
  • name (string): Domain name, OR
  • ip (string): IP address (dotted form)
• adminWebInterface (string, optional): Administrator web interface URL
• hostMaintenance (object, optional): Maintenance configuration:
  • oneShot (object): One-time maintenance (mutually exclusive with schedule):
  • start (string): Start time (ISO 8601 format)
  • timeMin (number): Duration in minutes
  • schedule (number): Schedule ID for regular maintenance (mutually exclusive with oneShot)
  • continueMonitoring (boolean, optional): Continue monitoring during maintenance
• settings (object, optional): Universal settings for this host

Result (on successful execution): Identifier of the created host (field id) + messages about ignored errors in the source data (field errors)

Request Example:

{
  "parentId": 1,
  "name": "Web Server 01",
  "config": {
    "hostDef": {
      "ip": "192.168.1.100"
    },
    "adminWebInterface": "https://192.168.1.100:8443"
  }
}

Response Example:

{
  "id": 25,
  "errors": []
}

Get Host

Function: get-host

Parameters:

• id (number): ID of the host

Result (on successful execution): Host-specific parameters of this host in the config field. In addition, the host name is output in the name field.

Response Example:

{
  "name": "My computer",
  "config": {
    "adminWebInterface": "http://$HostDNS:80",
    "hostDef": {
      "ip": "10.1.0.223"
    },
    "hostMaintenance": {
      "continueMonitoring": true,
      "oneShot": {
        "start": "2025-10-26T20:00:00",
        "timeMin": 60
      }
    }
  }
}

List Agents

Function: list-agents

Parameters: absent

Result (on successful execution): List of known agents (identifier, name) in the agents field

Response Example:

{
  "agents": [
    {"id": 1, "name": "Local Agent"},
    {"id": 3, "name": "New Agent"}
  ]
}

Monitor Management

Monitors are specific checks performed on hosts (ping, HTTP, SNMP, etc.). See Monitor Types for available types, Activity States for valid activity values, and Polling Interval Formats for interval configuration.

Create Monitor

Function: create-monitor

Parameters:

• parentType (string): Type of parent ("host" or "application")
• parentId (number): ID of the parent object
• name (string): Monitor name
• type (string): Monitor type (e.g., “ping”, “http”, “snmp”, etc.)
• activity (string, optional): Initial activity state. Valid values:
• "active": Monitor is active
• "stopped": Monitor is stopped
• "dep": Monitor is stopped due to dependency
• "maint": Monitor is in maintenance mode
• "discovered": Monitor is discovered but not yet active
• config (object): Monitor-specific configuration (as in get-monitor). In parameter names, case differences are ignored. You can also use only a substring of the parameter name (and of the value, in case if the parameter can have only a limited set of value variants), if the substring uniquely identifies the parameter/value.
• settings (object, optional): Universal settings for this monitor

Result (on successful execution): Identifier of the created monitor (field id) + messages about ignored errors in the source data (field errors)

Note: If the parameter value is an integer number, it can be specified either as integer, or as a string containing integer. If the parameter value represents a reference to another object, then its value can be specified either as a number (identifier) or as a string (in which case this is the name of the object).

Request Example (HTTP Monitor):

{
  "parentType": "host",
  "parentId": 5,
  "name": "HTTP Check",
  "type": "http",
  "activity": "active",
  "config": {
    "URL": "http://example.com/health",
    "Method": "GET"
  }
}

Request Example (PING Monitor):

{
  "parentType": "host",
  "parentId": 5,
  "name": "Server Ping",
  "type": "ping",
  "activity": "active",
  "config": {}
}

Response Example:

{
  "id": 156,
  "errors": []
}

Get Monitor

Function: get-monitor

Parameters:

• id (number): ID of the monitor

Result (on successful execution): Monitor-specific settings of this monitor in the config field. In addition, the monitor name is output in the name field and its type in the type field.

Note: Parameter names are given exactly as stored in the IPNetwork Monitor database. If the parameter value is an integer number, it is output as an integer number (not a string). If the parameter value is a reference to credentials, then its value is output as a credential identifier in the form of a number.

Response Example:

{
  "name": "Traffic speed total, kbit/s",
  "type": "WMI Traffic Speed",
  "config": {
    "Data Set": "Total Traffic",
    "Interface Bandwidth, kbits/s": 1000000,
    "Interface Name": "Intel[R] Ethernet Connection [7]",
    "Show Traffic Speed as": "a value in kbit/s"
  }
}

Monitor State

Function: monitor-state

Retrieves state and statistical data for a monitor.

Parameters:

• type (string): Type of data requested:
• "current": Current monitor state
• "history": Historical state changes
• "graph": Graph/chart data
• "stat": Statistical information
• id (number): Monitor ID
• start (string, optional): Start time point (ISO 8601 format, not applicable for current)
• finish (string, optional): End time point (ISO 8601 format, not applicable for current)

Result (on successful execution): Data about the state or statistics of the monitor

Response Example (type: "current"):

{
  "activity": "active",
  "current": 114,
  "lastpoll": "2025-10-26T17:07:02",
  "measure": "kbit/s",
  "state": "ok"
}

Response Example (type: "history"):

{
  "history": [
    {
      "activity": "active",
      "start": "2025-10-22T03:14:39",
      "state": "unknown",
      "stop": "2025-10-26T16:56:53"
    },
    {
      "activity": "active",
      "start": "2025-10-26T16:56:53",
      "state": "ok",
      "stop": "2025-10-26T17:14:02"
    }
  ]
}

Response Example (type: "graph"):

{
  "graph": [
    {
      "avg": 606,
      "max": 1944,
      "min": 67,
      "ndown": 0,
      "nok": 4,
      "npolls": 4,
      "nwarn": 0,
      "start": "2025-10-26T16:50:00"
    },
    {
      "avg": 253,
      "max": 1069,
      "min": 24,
      "ndown": 0,
      "nok": 10,
      "npolls": 10,
      "nwarn": 0,
      "start": "2025-10-26T17:00:00"
    }
  ]
}

Response Example (type: "stat"):

{
  "stat": [
    {
      "avg": 36,
      "max": 222,
      "min": 12,
      "ndown": 0,
      "nok": 30,
      "npolls": 30,
      "nwarn": 0,
      "pctactive": 100,
      "pctdown": 0,
      "pctok": 100,
      "pctwarn": 0,
      "start": "2025-10-09T23:30:00",
      "stop": "2025-10-10T00:00:00"
    }
  ]
}

Alerting System

Composite Alerts

Composite alerts combine multiple Simple Actions with optional Schedules. Alerts are triggered by Alerting Rules when monitors change state.

Create Alert

Function: create-alert

Parameters:

• name (string): Name of the composite alert to be created
• config (object): Alert parameters (list of simple actions with schedules)

Result (on successful execution): Identifier of the created alert (field id) + messages about ignored errors in the source data (field errors)

Request Example:

{
  "name": "Critical Server Down",
  "config": {
    "actions": [
      {
        "action": 1,
        "schedule": 2
      },
      {
        "action": 3
      }
    ]
  }
}

Response Example:

{
  "id": 10,
  "errors": []
}

Get Alert

Function: get-alert

Parameters:

• id (number): Alert ID

Result (on successful execution): Settings of the composite alert in the config field. In addition, the name of the alert is output in the name field.

Response Example:

{
  "config": {
    "actions": [
      {
        "action": 5,
        "schedule": 1
      }
    ]
  },
  "name": "Play Sound"
}

List Alerts

Function: list-alerts

Parameters: absent

Result (on successful execution): List of known composite alerts in the alerts field

Response Example:

{
  "alerts": [
    {"id": 0, "name": "<Do the same>"},
    {"id": 2, "name": "Popup + Send Push notification"}
  ]
}

Alerting Rules

Alerting rules define how monitors react to state changes (down, warning, ok). Rules reference Composite Alerts for each state transition. Rules can be assigned to objects via the alerting.rule setting (see Settings and Configuration).

Create Alerting Rule

Function: create-alerting-rule

Parameters:

• name (string): Name of the alerting rule to be created
• config (object): Rule parameters (in which cases to apply which alert)

Result (on successful execution): Identifier of the created rule (field id) + messages about ignored errors in the source data (field errors)

Request Example:

{
  "name": "Standard Alerting",
  "config": {
    "down": {
      "enter": {
        "delaySec": 60,
        "alert": 1,
        "recoveryAlert": 2
      },
      "extended": {
        "delayMin": 15,
        "alert": 1,
        "repeatMin": 30,
        "recoveryAlert": 2
      }
    },
    "warning": {
      "enter": {
        "delaySec": 120,
        "alert": 3
      }
    },
    "eventAlert": 4
  }
}

Response Example:

{
  "id": 15,
  "errors": []
}

Get Alerting Rule

Function: get-alerting-rule

Parameters:

• id (number): Rule ID

Result (on successful execution): Settings of the alerting rule in the config field. In addition, the name of the rule is output in the name field.

Response Example:

{
  "name": "New Alerting Rule",
  "config": {
    "down": {
      "enter": {
        "alert": 8,
        "recoveryAlert": null
      },
      "extended": {
        "alert": 8,
        "delayMin": 30,
        "recoveryAlert": null
      }
    },
    "eventAlert": 8,
    "name": "New rule",
    "warning": {
      "enter": {
        "alert": 6,
        "recoveryAlert": null
      },
      "extended": {
        "alert": 8,
        "delayMin": 30,
        "recoveryAlert": null
      }
    }
  }
}

List Alerting Rules

Function: list-alerting-rules

Parameters: absent

Result (on successful execution): List of known alerting rules in the rules field

Response Example:

{
  "rules": [
    {"id": 8, "name": "Default Alerting Rule"},
    {"id": 256, "name": "My Custom Rule"}
  ]
}

Schedules

Schedules define time windows for when actions should be executed (e.g., business hours only).

Create Schedule

Function: create-schedule

Parameters:

• name (string): Name of the schedule to be created
• config (object): Schedule parameters (working hours in each of the days of the week)

Result (on successful execution): Identifier of the created schedule (field id) + messages about ignored errors in the source data (field errors)

Request Example:

{
  "name": "Business Hours",
  "config": {
    "mon": "09:00-17:00",
    "tue": "09:00-17:00",
    "wed": "09:00-17:00",
    "thu": "09:00-17:00",
    "fri": "09:00-17:00",
    "sat": "",
    "sun": ""
  }
}

Response Example:

{
  "id": 4,
  "errors": []
}

Get Schedule

Function: get-schedule

Parameters:

• id (number): Schedule ID

Result (on successful execution): Settings of the schedule in the config field. In addition, the name of the schedule is output in the name field.

Response Example:

{
  "name": "Weird schedule",
  "config": {
    "mon": "12:00-13:00",
    "sun": "11:10-11:15",
    "wed": "14:00-15:00"
  }
}

List Schedules

Function: list-schedules

Parameters: absent

Result (on successful execution): List of known schedules in the schedules field

Response Example:

{
  "schedules": [
    {"id": 1, "name": "Always"},
    {"id": 3, "name": "Working hours"}
  ]
}

Actions

Simple actions are individual actions that can be triggered by Composite Alerts. See Simple Action Types for available action types and their configuration parameters.

Create Simple Action

Function: create-simple-action

Parameters:

• name (string): Name of the simple action to be created
• type (string): Type of simple action (e.g., “Send mail”)
• config (object): Action parameters (if required). In parameter names, case differences are ignored. You can also use only a substring of the parameter name (and of the value, in case if the parameter can have only a limited set of value variants), if the substring uniquely identifies the parameter/value.

Result (on successful execution): Identifier of the created action (field id) + messages about ignored errors in the source data (field errors)

Request Example (Email Action):

{
  "name": "Send Email Alert",
  "type": "Send mail",
  "config": {
    "To": "admin@example.com",
    "Subject": "$MonitorName is $MonitorState"
  }
}

Request Example (Execute Program Action):

{
  "name": "Run Restart Script",
  "type": "Execute program",
  "config": {
    "Program Name": "/usr/local/bin/restart-service.sh",
    "Arguments": "$HostIP $MonitorName"
  }
}

Response Example:

{
  "id": 8,
  "errors": []
}

Get Simple Action

Function: get-simple-action

Parameters:

• id (number): Action ID

Result (on successful execution): Settings of this simple action in the config field. In addition, the action name is output in the name field and its type in the type field.

Response Example:

{
  "name": "New action",
  "config": {
    "Simple Alert Credentials": 0,
    "Arguments": "",
    "Program Name": "crazy",
    "Program Type": "Run program"
  },
  "type": "Execute program"
}

List Simple Actions

Function: list-simple-actions

Parameters: absent

Result (on successful execution): List of known simple actions in the actions field

Response Example:

{
  "actions": [
    {"id": 1, "name": "Pop-up window", "type": "Pop-up window"},
    {"id": 3, "name": "Send mail", "type": "Send mail"}
  ]
}

Settings and Configuration

Settings Structure

Universal settings can be attached to any object in the hierarchy and are inherited by child objects. Settings include:

Polling Configuration

• pollingInterval (string): How often to poll the monitor. Includes the time units, i.e. “100 sec” or “2 min”.

Dependency Settings

• dependencySettings (object):
• mode (enum): "none" (no dependency), "ping" (dependency on PING monitor on the same host), or "other" (dependency on some other monitor)
• monitor (number, optional): Monitor ID for "other" mode
• state (enum): "down", "warning", or "ok" (the state of dependency monitor when the polling on the dependent monitor stops)
• reverse (boolean): Reverse dependency logic (stop polls if the dependency monitor is NOT in the selected state)
• dependOnLink (boolean): Depend on agent being online

Credentials

• credentials (object):
• unix (number, optional): Unix credentials ID
• windows (number, optional): Windows credentials ID
• snmp (number, optional): SNMP credentials ID

State Conditions

State conditions define when a monitor changes state (DOWN, WARNING, OK). Each monitor type supports its own set of state conditions, and only supported state conditions can be attached to a given monitor. However, any condition can be attached to a container (i.e., host or host group).

Note: Besides the common spike filter, some state conditions have their specific spike filters.

Error State Conditions (DOWN)

• spikeFilter (number|null): Number of consecutive failures before alerting. Null means no spike filtering.
• responseTimeout (object):
• timeoutMsec (number): Timeout in milliseconds
• spikeFilter (object, optional): Spike filter for timeout
• htmlResponseValidation (object):
• mode (enum): "none", "contain", "not-contain"
• strings (array): Strings to check for
• regexp (boolean): Use regular expressions
• caseInsensitive (boolean): Case-insensitive matching
• httpResponseCodeValidation (object):
• allow (string): Comma-separated accepted codes (e.g., “2xx,300”)
• except (string): Comma-separated rejected codes
• valueBounds (object):
• lower (number): Lower bound
• upper (number): Upper bound
• spikeFilter (object, optional): Spike filter configuration
• speedLimit (object):
• value (number): Limit value
• unit (enum): "%", "kb/s", or "Mb/s"
• spikeFilter (object, optional)
• volumeLimit (object):
• value (number): Limit value
• unit (enum): "kb", "Mb", or "Gb"
• spikeFilter (object, optional)
• dnsResponseValidation (object):
• mode (enum): "none", "match", "not-match", "contain", "not-contain"
• strings (array): Strings to validate
• regexp (boolean): Use regular expressions
• stringResponseValidation (object):
• mode (enum): "none", "match", "not-match", "contain", "not-contain"
• strings (array): Strings to validate
• regexp (boolean): Use regular expressions
• caseInsensitive (boolean): Case-insensitive matching
• eventTimeout (object):
• sec (number): Maximum time between events in seconds
• spikeFilter (object, optional)
• additionalIntervalSec (number, optional): Additional interval between bad polls
• trapPayload (object):
• mode (enum): "none", "contain", "not-contain"
• string (string): Substring to check for

Warning state conditions follow the same structure as error conditions.

Alerting Configuration

• alerting (object):
• rule (number, optional): ID of named alerting rule, OR
• specific (object, optional): Object-specific alerting rule (same structure as alerting rule config)

Get Settings

Function: settings

Gets inheritable settings attached to a specific object (not including inherited values).

Parameters:

• type (string): Object type ("root", "agent", "hostgroup", "host", "application", or "monitor")
• id (number): Object ID

Result (on successful execution): Common settings attached to this object (without inherited from parents) in the settings field

Response Example:

{
  "settings": {
    "alerting": {
      "rule": 8
    },
    "dependencySettings": {
      "mode": "other",
      "monitor": 13,
      "state": "warning"
    },
    "pollingInterval": "600 sec",
    "stateConditions": {
      "error": {
        "responseTimeout": {
          "timeoutMsec": 10550
        }
      },
      "warning": {
        "responseTimeout": {
          "spikeFilter": {
            "count": 2
          },
          "timeoutMsec": 20222
        },
        "spikeFilter": 10
      }
    }
  }
}

Get Effective Settings

Function: effective-settings

Gets effective settings for an object, taking inheritance into account.

Parameters:

• type (string): Object type ("root", "agent", "hostgroup", "host", "application", or "monitor")
• id (number): Object ID

Result (on successful execution): Common settings of this object (taking into account inherited from parents). The output format is the same as in settings.

Get Parent

Function: get-parent

Gets the parent object of a specified object.

Parameters:

• type (string): Type of the examined object ("root", "agent", "hostgroup", "host", "application", or "monitor")
• id (number): Object ID

Result (on successful execution): Data about the parent object

Response Example:

{
  "type": "host",
  "id": 15
}

Monitoring and State

Monitor States

Monitors can be in one of three states:

• OK: Monitor is functioning normally
• WARNING: Monitor is in a warning condition
• DOWN: Monitor has failed or is unavailable

State Transitions

State changes trigger alerts based on: 1. Entering a state (with optional delay) 2. Extended state (state persists for extended period) 3. Recovery from a state

Spike Filters

Spike filters prevent false positives by requiring multiple consecutive failures before changing state. This helps handle temporary network issues. Besides the common spike filter, some state conditions have their specific spike filters. The structure of specific spike filter is as follows:

• count (number, optional): Number of consecutive failures before alerting.

Reference Tables

Monitor Types

The following monitor types are available for use with create-monitor. Use the exact string value in the type parameter.

Note: Monitor type names are case-insensitive. Partial matching is supported if the substring uniquely identifies the type.

Simple Action Types

The following action types are available for use with create-simple-action. Use the exact string value in the type parameter.

Note: Action type names are case-insensitive. Partial matching is supported if the substring uniquely identifies the type.

Host Icon Files

Common icon filenames for the hostIcon parameter in host configuration and defaultHostIcon in host group configuration.

Host Group Kinds

Valid values for the kind parameter in host group configuration.

Activity States

Valid values for the activity parameter in monitor creation and state queries.

Polling Interval Formats

The pollingInterval setting accepts strings with time units.

Best Practices

1. Organize with Host Groups: Use host groups to logically organize hosts and apply common settings.
2. Leverage Settings Inheritance: Configure common settings at higher levels (host groups, agents) to reduce duplication. Use effective-settings to verify inherited values.
3. Use Alerting Rules: Create reusable alerting rules for consistent alert behavior across monitors.
4. Configure Spike Filters: Use spike filters to prevent false alerts from temporary network issues.
5. Schedule Maintenance: Use maintenance windows and schedules to prevent alerts during planned downtime.
6. Monitor Dependencies: Configure monitor dependencies to prevent cascading alerts when upstream services fail.
7. Use Credentials Management: Centralize credential management for easier updates and security.

Error Handling

When using the IPNetwork MCP service, all functions return structured responses. This section describes common error scenarios and their responses.

Response Structure

Successful Response

All successful operations return a result object. For create operations, this includes the new object’s ID:

{
  "id": 42,
  "errors": []
}

The errors array may contain warnings about ignored invalid parameters even when the operation succeeds.

Error Response

When an operation fails, an error message is returned:

{
  "error": "Object not found",
  "code": "NOT_FOUND"
}

Common Error Scenarios

Invalid Object ID

Scenario: Requesting an object that doesn’t exist.

Request: get-host with id: 99999

Response:

{
  "error": "Host with ID 99999 not found"
}

Invalid Parent Reference

Scenario: Creating an object with a non-existent parent.

Request: create-host with parentId: 99999

Response:

{
  "error": "Parent host group with ID 99999 not found"
}

Invalid Parameter Value

Scenario: Providing an invalid value for a parameter.

Request: create-monitor with type: "invalid_type"

Response:

{
  "error": "Unknown monitor type: invalid_type"
}

Missing Required Parameter

Scenario: Omitting a required parameter.

Request: create-host without name

Response:

{
  "error": "Missing required parameter: name"
}

Partial Success with Warnings

Scenario: Object created but some parameters were ignored.

Request: create-monitor with an unrecognized config parameter

Response:

{
  "id": 123,
  "errors": [
    "Unknown parameter 'InvalidParam' ignored"
  ]
}

Authentication Error

Scenario: Using an invalid or expired token.

Response:

{
  "error": "Authentication failed: Invalid token"
}

Permission Denied

Scenario: Using a read-only token for a write operation.

Response:

{
  "error": "Permission denied: Read-only token cannot perform create operations"
}

Error Handling Best Practices

1. Always check for errors: Even successful responses may contain warnings in the errors array
2. Validate IDs: Before referencing objects, verify they exist using list-* or get-* functions
3. Use descriptive names: When referencing objects by name instead of ID, ensure names are unique
4. Handle partial failures: Log warnings from the errors array for debugging

Troubleshooting

Connection Issues

Cannot Connect to MCP Server

Symptoms: Connection refused or timeout when accessing the MCP API.

Possible Causes: 1. MCP service is disabled 2. Firewall blocking the MCP port 3. Incorrect binding address configuration

Solutions: 1. Enable MCP in Settings → MCP page 2. Verify the MCP port is open in your firewall 3. Check the binding address (use 0.0.0.0 for all interfaces or 127.0.0.1 for localhost only)

SSL/TLS Certificate Errors

Symptoms: Certificate validation errors when connecting.

Solutions: 1. Ensure you’re using HTTPS (not HTTP) 2. Import the IPNetwork Monitor certificate to your trusted store 3. For testing, you may need to disable certificate validation in your client

Authentication Issues

Token Not Accepted

Symptoms: Authentication errors despite using a copied token.

Possible Causes: 1. Token was regenerated after copying 2. Whitespace included when copying the token 3. Using read-only token for write operations

Solutions: 1. Copy the token again from the MCP settings page 2. Ensure no leading/trailing whitespace in the token 3. Use the read-write token for create/modify operations

Object Creation Issues

Duplicate Names

Symptoms: Created object has a modified name (e.g., “Server #2”).

Explanation: This is expected behavior. When an object with the same name exists, IPNetwork automatically appends a number suffix.

Solution: Use unique names, or accept the auto-generated suffix.

Parameters Ignored

Symptoms: Object created but some settings not applied.

Possible Causes: 1. Parameter name misspelled 2. Parameter not applicable to this object type 3. Invalid parameter value

Solutions: 1. Check parameter names against documentation (case-insensitive, but must be spelled correctly) 2. Verify the parameter is supported for the specific monitor/action type 3. Check the errors array in the response for specific warnings

Monitor Issues

Monitor Shows “Unknown” State

Symptoms: Newly created monitor stays in “unknown” state.

Possible Causes: 1. Monitor is not active 2. First poll hasn’t completed yet 3. Dependency blocking the monitor

Solutions: 1. Verify activity is set to "active" 2. Wait for the polling interval to elapse 3. Check dependency settings with effective-settings

Monitor Always Down

Symptoms: Monitor shows DOWN state but target is reachable.

Possible Causes: 1. Incorrect host definition (IP/hostname) 2. Credentials not configured or incorrect 3. State conditions too strict

Solutions: 1. Verify hostDef in host configuration 2. Check and update credentials 3. Review stateConditions in effective settings

Performance Issues

Slow API Responses

Symptoms: API calls take longer than expected.

Possible Causes: 1. Large number of objects being queried 2. Server under heavy load

Solutions: 1. Use specific queries instead of listing all objects 2. Consider the server’s monitoring load when making bulk API calls

Glossary

API Reference Summary

All Functions by Category

Credentials Management

Host and Group Management

Monitor Management

Alerting System

Schedules

Actions

Settings

Quick Reference: Common Parameters

Quick Reference: Object Types