Getting Started with IPNetwork MCP API

MCP API

The IPNetwork Monitor MCP (Model Context Protocol) API opens up a new way to manage your network monitoring infrastructure. Instead of clicking through the UI, you can use AI-powered tools like Claude Code and Cursor to create hosts, configure monitors, set up alerting rules, and query monitoring data — all through natural language conversations.

This guide walks you through enabling the MCP server, connecting it to your favorite AI coding tools, and running your first API calls.

Table of Contents

Configuring the MCP Server

Enabling MCP in IPNetwork Monitor

The MCP server is built into IPNetwork Monitor but is disabled by default. To enable it:

  1. Open IPNetwork Monitor and go to Settings.
  2. Navigate to the MCP tab.
  3. Check Enable MCP Server.

Configure the connection settings:

  • Port — the TCP port the MCP server listens on (8888 by default).
  • Binding address — the local network interface to listen on. Use 0.0.0.0 to accept connections from any interface, or 127.0.0.1 to restrict access to the local machine only.
  • External hostname — the public hostname that MCP clients will use to reach the server. If you are using port forwarding or a tunneling service where the public port differs from the local port, specify it explicitly (e.g. abc.ngrok.app:443).
  • MCP endpoint URL — a read-only field showing the final connection URL. Copy this URL to your MCP client configuration.

Configure access tokens:

  • Read-write token — grants full access to the MCP API, including creating and modifying objects.
  • Read-only token — grants restricted access for viewing data only.

Click Generate new to create random tokens. Use the read-only token for integrations that only need to query data. Regenerate tokens immediately if you suspect they have been compromised.

Note: The MCP server shares the same SSL certificate configuration as the Web Interface. For HTTPS connections to work correctly, the domain name in your External hostname must match the Common Name in the SSL certificate.

Making the MCP Server Accessible Remotely

If your IPNetwork Monitor is running on a local network or behind a firewall, you’ll need to make the MCP server accessible to external AI tools. Here are two common approaches.

Option 1: SSH Port Forwarding

SSH port forwarding is the simplest and most secure option when you have SSH access to the machine running IPNetwork Monitor (or to a machine on the same network).

Forward the MCP port to your local machine:

ssh -L 8888:localhost:8888 user@your-ipnetwork-server

This maps port 8888 on your local machine to port 8888 on the remote server. You can then connect your MCP client to:

https://localhost:8888/mcp

If IPNetwork Monitor is on a different host within the remote network:

ssh -L 8888:192.168.1.100:8888 user@jump-server

This forwards through jump-server to the IPNetwork Monitor at 192.168.1.100.

Tip: Add -N to the SSH command if you don’t need a shell session (e.g. ssh -N -L 8888:localhost:8888 user@server).

Option 2: ngrok Tunnel

ngrok creates a public HTTPS tunnel to your local MCP server without requiring any firewall changes.

  1. Install ngrok from https://ngrok.com/download and authenticate:
ngrok config add-authtoken YOUR_NGROK_TOKEN
  1. Start the tunnel:
ngrok http https://localhost:8888

ngrok will display a public URL like https://abc123.ngrok-free.app.

  1. Update IPNetwork Monitor settings:
  2. Set External hostname to the ngrok URL (e.g. abc123.ngrok-free.app:443)
  3. Copy the updated MCP endpoint URL
  4. Use the ngrok URL in your MCP client configuration:
https://abc123.ngrok-free.app/mcp

Note: Free ngrok URLs change each time you restart the tunnel. For a stable URL, consider a paid ngrok plan or use SSH forwarding instead.

Python Client Examples

We provide a set of Python examples demonstrating common MCP API operations. The source code is available on GitHub:

https://github.com/IPNetwork-Monitor-LLC/ipnetwork-mcp-examples

The repository includes a reusable Python MCP client wrapper and five progressive examples:

Example Description
01_basic_connection.py Connect to the MCP server and list available agents
02_create_host.py Create a host with Ping and HTTP monitors
03_alerting_setup.py Set up email alerts, schedules, and alerting rules
04_monitor_state.py Query current state, history, and statistics
05_bulk_operations.py Bulk create multiple hosts and monitors

Quick start:

git clone https://github.com/IPNetwork-Monitor-LLC/ipnetwork-mcp-examples.git
cd ipnetwork-mcp-examples
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

export MCP_URL="https://your-server:8888/mcp"
export MCP_TOKEN="your-read-write-token"

python examples/01_basic_connection.py

Using IPNetwork MCP API in Claude Code

Claude Code is Anthropic’s CLI tool for AI-assisted software development. Adding the IPNetwork MCP server lets Claude interact with your monitoring infrastructure directly.

Adding the MCP Server to Claude Code

Using the CLI (recommended):

claude mcp add --transport http ipnetwork-monitor \
  https://your-server:8888/mcp \
  --header "Authorization: Bearer YOUR_READ_WRITE_TOKEN"

Or create a .mcp.json file in your project root:

{
  "mcpServers": {
    "ipnetwork-monitor": {
      "type": "http",
      "url": "https://your-server:8888/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_READ_WRITE_TOKEN"
      }
    }
  }
}

Tip: Use environment variables to keep tokens out of version control: json { "mcpServers": { "ipnetwork-monitor": { "type": "http", "url": "${MCP_URL:-https://localhost:8888/mcp}", "headers": { "Authorization": "Bearer ${MCP_TOKEN}" } } } } }

Verify the connection by launching Claude Code and running /mcp to check the server status. You should see ipnetwork-monitor listed with its available tools.

Claude Code Example Session

Once connected, you can manage your monitoring infrastructure through natural conversation:

You: List all agents and their hosts

Claude: Let me query the MCP server.
        [Calls list-agents, list-children]

        Agent: Local Agent (ID: 1)
        ├── Servers
        │   ├── Web Server (192.168.1.10)
        │   └── Database Server (192.168.1.20)
        └── Network Equipment
            └── Core Switch (10.0.0.1)
You: Create a new host "Production API" with IP 10.0.1.50
     in the Servers group, and add a Ping monitor and an
     HTTP monitor checking https://api.example.com/health

Claude: I'll create the host and monitors.
        [Calls create-host, create-monitor x2]

        Created:

        - Host "Production API" (ID: 15)
        - Ping monitor (ID: 42) — polling every 1 min
        - HTTP monitor (ID: 44) — checking /health every 2 min,
          depends on Ping
You: Show me which monitors are currently down

Claude: [Calls list-agents, list-children, monitor-state]

        All monitors are OK except:

        - Web Server > HTTP Check: DOWN since 14:32
          (last value: timeout after 30000 msec)

Using IPNetwork MCP API in Cursor IDE

Cursor is an AI-powered code editor. Adding the IPNetwork MCP server lets Cursor’s AI assistant work with your monitoring configuration.

Adding the MCP Server to Cursor

  1. Open Cursor and go to Settings > Tools & MCP.
  2. Click + Add new MCP server.
  3. Select Type: Streamable HTTP, enter the server URL and save.

Or create a .cursor/mcp.json file in your project root:

{
  "mcpServers": {
    "ipnetwork-monitor": {
      "url": "https://your-server:8888/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_READ_WRITE_TOKEN"
      }
    }
  }
}

For a global configuration (available in all projects), create the file at:

  • macOS: ~/.cursor/mcp.json
  • Linux: ~/.config/cursor/mcp.json
  • Windows: %APPDATA%\Cursor\mcp.json

After adding the server, return to Settings > Tools & MCP to verify the connection shows a green status indicator.

Cursor Example Session

Open the AI chat in Cursor (Ctrl+L / Cmd+L) and interact with your monitoring setup:

You: What monitors do we have on the my-win2019 host?

Cursor: [Calls list-children for the host]

        The host "my-win2019" has 10 monitors:

        - PING — OK (1 msec)
        - CPU usage — OK (54%)
        - Free disk space on C: — WARNING (2%)
        - Web Interface — OK (5 msec)
        - Free physical memory — OK
        - Traffic speed total — OK (114 kbit/s)
        ...
You: Set up email alerting for the Servers group:
     send alerts to ops@mycompany.com when any monitor
     goes down, with a 60 second delay

Cursor: [Calls create-simple-action, create-alert,
         create-alerting-rule, then applies to host group]

        Done! Created alerting pipeline:
        1. Email action → ops@mycompany.com
        2. Alerting rule: 60s delay on DOWN, recovery alerts
        3. Applied to "Servers" host group (inherited by all
           hosts and monitors)
You: Create a script that checks all monitors and
     sends a summary to Slack

Cursor: Sure, I'll query the current API structure first.
        [Calls list-agents, list-children, monitor-state]

        Here's a Python script using the MCP client library...

What’s Next