1.1 Product Overview

MeshOptixIQ is a vendor-agnostic network intelligence platform that collects live operational state from network devices, normalises it into a canonical graph model, and exposes the resulting topology for query, visualisation, and AI-assisted reasoning.

Rather than scraping device CLIs for ad-hoc troubleshooting, MeshOptixIQ builds a persistent, queryable model of your network — one that supports blast-radius analysis, endpoint hunting, IP-addressing audits, and firewall policy review without requiring manual correlation across multiple management systems.

Who Should Read This Guide

This guide is written for network engineers, systems administrators, and DevOps teams deploying MeshOptixIQ in production environments. Familiarity with Linux system administration, SSH, and basic IP networking concepts is assumed.

1.2 Key Capabilities

1.3 System Architecture

MeshOptixIQ is composed of four logical layers:

1. Collection layer — meshq collect connects to devices over SSH using Netmiko, retrieves CLI output, and writes raw text to a local cache directory.
2. Normalisation layer — meshq parse reads the raw cache and produces vendor-agnostic Pydantic models (devices, interfaces, IPs, MACs, VLANs, endpoints, firewall rules, address objects, service objects).
3. Graph layer — meshq ingest writes the normalised models into Neo4j or PostgreSQL. The graph schema represents devices as nodes, connections as relationships, and all other facts as node properties or related nodes.
4. Query layer — A FastAPI service exposes 23 named queries via /queries/. The same queries are available via the MCP server (meshq-mcp) for AI-assistant integration. A React/Vite single-page application provides the web interface.

  ┌──────────────────────────────────────────────────────┐
  │  Network Devices  (SSH / Netmiko)                   │
  └──────────────┬───────────────────────────────────────┘
                 │ raw CLI text
  ┌──────────────▼───────────────────────────────────────┐
  │  meshq collect → local cache (~/.meshoptixiq/cache/) │
  └──────────────┬───────────────────────────────────────┘
                 │ parsed models (Pydantic)
  ┌──────────────▼───────────────────────────────────────┐
  │  meshq parse → meshq ingest → Neo4j / PostgreSQL     │
  └──────────────┬───────────────────────────────────────┘
                 │ Cypher / SQL queries
  ┌──────────────▼──────────────┬────────────────────────┐
  │  FastAPI Query API          │  MCP Server (stdio)    │
  │  /queries/*  :8000          │  meshq-mcp             │
  └──────────────┬──────────────┴────────────────────────┘
                 │
  ┌──────────────▼───────────────────────────────────────┐
  │  React Web UI  (served by FastAPI at /static)        │
  └──────────────────────────────────────────────────────┘

1.4 License Plans

2.1 Host Requirements

2.2 Database Requirements

Neo4j (Default)

Neo4j must be reachable over the Bolt protocol (default port 7687). HTTP/HTTPS (7474) is optional and used only for the Neo4j Browser UI.

PostgreSQL (Pro/Enterprise Alternative)

PostgreSQL 14 or later. The psycopg v3 driver (psycopg[binary]) is required. Install the postgres extras: pip install "meshoptixiq-network-discovery[postgres]".

2.3 Network Requirements

3.1 Docker Installation (Recommended)

The official Docker image bundles the FastAPI query API, the React web UI, and the Cython-compiled licensing module. It is the fastest path to a working deployment.

Step 1 — Pull the Image

docker pull meshoptixiq/discovery-agent:latest

Step 2 — Start Neo4j

docker run -d \
  --name neo4j \
  -p 7687:7687 -p 7474:7474 \
  -e NEO4J_AUTH=neo4j/your-password \
  -v neo4j-data:/data \
  neo4j:5-community

Step 3 — Start MeshOptixIQ

docker run -d \
  --name meshoptixiq \
  -p 8000:8000 \
  --link neo4j:neo4j \
  -e GRAPH_BACKEND=neo4j \
  -e NEO4J_URI=bolt://neo4j:7687 \
  -e NEO4J_USER=neo4j \
  -e NEO4J_PASSWORD=your-password \
  -e MESHOPTIXIQ_LICENSE_KEY=mq-prod-xxxxxxxxxx \
  -e API_KEY=your-api-key-here \
  -v meshoptixiq-cache:/app/cache \
  meshoptixiq/discovery-agent:latest

Step 4 — Verify

curl http://localhost:8000/health
# {"status":"ok"}

curl http://localhost:8000/health/ready
# {"status":"ok","backend":"neo4j"}

3.2 Python Package Installation

Install directly from PyPI for environments where Docker is not available or for development use.

Base Installation

pip install meshoptixiq-network-discovery

With PostgreSQL Support

pip install "meshoptixiq-network-discovery[postgres]"

With MCP Server

pip install "meshoptixiq-network-discovery[mcp]"

Full Installation (All Extras)

pip install "meshoptixiq-network-discovery[postgres,mcp]"

Verify CLI Installation

meshq version
# MeshOptixIQ Network Discovery v1.0.0
# License: Pro (Expires: 2027-12-31)

3.3 License Activation

MeshOptixIQ requires a valid license key for all operations beyond basic collection. Keys are issued at meshoptixiq.com/pricing and take the form mq-prod-xxxxxxxxxx.

Method A — Environment Variable (Recommended for Docker)

export MESHOPTIXIQ_LICENSE_KEY="mq-prod-xxxxxxxxxx"

Pass this to Docker with -e MESHOPTIXIQ_LICENSE_KEY or include it in a .env file with Docker Compose.

Method B — License File (Recommended for Bare-Metal)

mkdir -p ~/.meshoptixiq
echo "mq-prod-xxxxxxxxxx" > ~/.meshoptixiq/license.key
chmod 600 ~/.meshoptixiq/license.key

The application checks the file path ~/.meshoptixiq/license.key on startup; the environment variable takes precedence if both are present.

Device Registration

On first startup, MeshOptixIQ registers the host device fingerprint (based on hostname, MAC address, and CPU architecture) with the licensing server. Pro licenses support up to 5 registered devices; Enterprise licenses are unlimited.

3.4 Verifying the Installation

1. Check the CLI version and license status: meshq version
2. Verify database connectivity: curl http://localhost:8000/health/ready
3. List available queries: curl -H "X-API-Key: $API_KEY" http://localhost:8000/queries/
4. Open the web UI: navigate to http://localhost:8000 in a browser

A successful installation shows 25 queries in the API response and the topology graph in the web UI (empty until data is collected).

4.1 Environment Variables

All configuration is driven by environment variables. No configuration files are required. See Appendix A for the complete reference; the most critical variables are listed below.

4.2 Neo4j Backend Configuration

Connection String Formats

# Local bolt (default)
NEO4J_URI=bolt://localhost:7687

# TLS-encrypted bolt
NEO4J_URI=bolt+s://neo4j.internal:7687

# Aura cloud (always TLS)
NEO4J_URI=neo4j+s://xxxxxxxx.databases.neo4j.io

Schema Initialisation

On first ingest, MeshOptixIQ creates uniqueness constraints and indexes automatically. To apply constraints manually (recommended before bulk ingest):

meshq ingest --init-schema

Performance Tuning

For networks with more than 200 devices, increase Neo4j heap allocation in neo4j.conf:

dbms.memory.heap.initial_size=1G
dbms.memory.heap.max_size=4G
dbms.memory.pagecache.size=2G

4.3 PostgreSQL Backend Configuration

The PostgreSQL backend stores topology data in relational tables with array columns for multi-value fields (zones, addresses, services in firewall rules). It is functionally equivalent to the Neo4j backend for all 25 queries.

export GRAPH_BACKEND=postgres
export POSTGRES_DSN="postgresql://meshoptixiq:password@db.internal:5432/meshoptixiq"

Schema Creation

The schema is applied automatically on first ingest. Tables created include: devices, interfaces, ip_addresses, subnets, vlans, mac_addresses, endpoints, firewall_rules, address_objects, service_objects.

4.4 API Authentication

The Query API uses a shared API key passed in the X-API-Key HTTP header. API_KEY is required — the server will exit at startup if it is not set.

# Set a strong random key (32+ characters)
export API_KEY=$(openssl rand -hex 32)

# All API requests must include the header
curl -H "X-API-Key: $API_KEY" http://localhost:8000/queries/

CORS Configuration

Restrict CORS to your specific UI origin in production:

export CORS_ORIGINS="https://meshoptixiq.yourdomain.com,https://admin.yourdomain.com"

5.1 Supported Vendors & OS Types

5.2 Inventory File Format

Devices are defined in a YAML inventory file. By convention this file is named inventory.yaml and stored in the project directory.

devices:
  # Cisco IOS core switch
  - hostname: sw-core-01
    host: 10.0.0.1
    device_type: cisco_ios
    username: netops
    password: "{{ env.SWITCH_PASSWORD }}"
    port: 22
    timeout: 30

  # Arista EOS distribution switch
  - hostname: sw-dist-01
    host: 10.0.0.2
    device_type: arista_eos
    username: netops
    password: "{{ env.SWITCH_PASSWORD }}"

  # PAN-OS firewall (includes firewall policy collection)
  - hostname: fw-edge-01
    host: 10.0.0.10
    device_type: paloalto_panos
    username: admin
    password: "{{ env.FW_PASSWORD }}"

  # Juniper SRX firewall
  - hostname: fw-srx-01
    host: 10.0.0.11
    device_type: juniper_junos
    username: netops
    password: "{{ env.FW_PASSWORD }}"

  # Fortinet FortiGate
  - hostname: fw-fg-01
    host: 10.0.0.12
    device_type: fortinet
    username: admin
    password: "{{ env.FW_PASSWORD }}"

  # Cisco ASA
  - hostname: fw-asa-01
    host: 10.0.0.13
    device_type: cisco_asa
    username: cisco
    password: "{{ env.FW_PASSWORD }}"

Supported device_type Values

Credential Security

Never store credentials in plain text in inventory files. Use environment variable references ({{ env.VAR_NAME }}) or a secrets manager. For Docker deployments, use Docker Secrets or pass credentials via environment variables.

5.3 Running Collection

Collect Raw Data

# Collect from all devices in the inventory file
meshq collect --source inventory.yaml

# Collect from a specific device (by hostname)
meshq collect --source inventory.yaml --device sw-core-01

# Collect with a higher timeout (seconds, default 30)
meshq collect --source inventory.yaml --timeout 60

# Run in parallel (default 4 workers; increase for large networks)
meshq collect --source inventory.yaml --workers 8

Raw CLI output is saved to ~/.meshoptixiq/cache/<hostname>/. Each collection run overwrites the previous cache for that device.

Check Collection Status

meshq status
# Shows last collection time, device count, and any collection errors

Scheduling Regular Collection

For continuous network intelligence, schedule collection with cron or a container orchestrator:

# Cron example — collect every 4 hours
0 */4 * * * /usr/local/bin/meshq collect --source /opt/meshoptixiq/inventory.yaml \
  && /usr/local/bin/meshq parse \
  && /usr/local/bin/meshq ingest

5.4 Parsing and Ingestion

Parse Cached Data

# Parse all cached device data
meshq parse

# Parse a specific device only
meshq parse --device sw-core-01

Parsing produces normalised Pydantic models and reports counts: devices, interfaces, IPs, MACs, VLANs, endpoints. Parsing errors are reported per-device and do not abort the run.

Ingest into Graph

# Ingest parsed data into the configured graph backend
meshq ingest

# Ingest and reinitialise schema constraints first
meshq ingest --init-schema

# Ingest from a specific parsed file
meshq ingest --file /path/to/facts.json

One-Command Pipeline

# Collect, parse, and ingest in sequence
meshq collect --source inventory.yaml \
  && meshq parse \
  && meshq ingest

Verifying Ingested Data

# Check summary counts via the API
curl -H "X-API-Key: $API_KEY" \
  http://localhost:8000/queries/summary_stats/execute \
  -H "Content-Type: application/json" \
  -d '{"parameters": {}}'

# Expected response
{
  "total": 1,
  "rows": [{
    "device_count": 12,
    "interface_count": 247,
    "endpoint_count": 1843,
    "vlan_count": 18
  }]
}

6.1 Supported Firewall Vendors

Graph Nodes Created

6.2 Collection Workflow

Firewall collection uses the same inventory file as topology collection. Ensure firewall devices are listed with the correct device_type (paloalto_panos, juniper_junos, fortinet, cisco_asa, cisco_ftd, or checkpoint_gaia).

# Collect all devices including firewalls
meshq collect --source inventory.yaml

# Parse — automatically detects and processes firewall output
meshq parse

# Ingest — writes FirewallRule, AddressObject, ServiceObject nodes
meshq ingest

Verifying Firewall Data

# List all firewalls with collected rules
curl -H "X-API-Key: $API_KEY" \
  http://localhost:8000/queries/all_firewall_devices/execute \
  -d '{"parameters": {}}'

# Get rules for a specific device
curl -H "X-API-Key: $API_KEY" \
  http://localhost:8000/queries/firewall_rules_by_device/execute \
  -d '{"parameters": {"device": "fw-edge-01"}}'

Deny Rules Summary

curl -H "X-API-Key: $API_KEY" \
  http://localhost:8000/queries/deny_rules_summary/execute \
  -d '{"parameters": {}}'

6.3 Path Analysis

Path analysis evaluates firewall rules for a given source IP, destination IP, and optional protocol/port. The query returns the first-matching rule per firewall along the path; firewalls with no matching rule are treated as implicit default-deny.

# Check if TCP/443 is permitted: 10.0.0.1 → 10.1.0.100
curl -H "X-API-Key: $API_KEY" \
  http://localhost:8000/queries/path_analysis/execute \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "source_ip": "10.0.0.1",
      "destination_ip": "10.1.0.100",
      "protocol": "tcp",
      "destination_port": "443"
    }
  }'

The response includes the matching rule for each firewall, its action (permit/deny/drop), rule name, and zone pair. Use the Path Analysis page in the web UI for an interactive view with a PERMITTED / DENIED verdict banner.

User Access Levels

Personas are access levels that control which pages and features are available to you in the web interface. Each persona unlocks a progressively larger part of the application, so you only see what is relevant to your role.

Your current persona is shown as a badge in the User menu at the top-right of every page. In the default single-user setup (API key authentication), you automatically receive the admin persona and have full access to every page. If your organisation has configured role-based access control Pro+, your persona is determined by the roles or groups assigned to your account — contact your administrator if you cannot reach a page you expect to see.

Dashboard (/)

The Dashboard is the home page you see when you open the web interface. It gives you an at-a-glance overview of the current state of your network:

• Network summary — counts of collected devices, interfaces, IP addresses, endpoints, VLANs, and firewall rules updated every few minutes.
• Security posture panel — hygiene indicators showing devices without neighbours, interfaces without IPs, and endpoints without subnet assignments. Each indicator is a shortcut to the relevant detail page.
• Network mini-map — a compact thumbnail of the topology graph so you can spot changes at a glance without switching to the full Topology view.
• Live activity badge — the status bar at the top shows whether the server is reachable and whether real-time updates are streaming.

The Dashboard does not require any specific persona — it is available to every user regardless of access level.

7.1 App Shell & Navigation

Top Bar

A fixed bar at the top of every page provides at-a-glance status and global shortcuts:

• Global search button — click to open the Command Palette (or press Cmd+K / Ctrl+K from anywhere)
• Backend health dot — green (reachable), amber (degraded), red (unreachable); the label reads "Live" or "Offline" so colour-blind users are not excluded
• Live / Polling badge — "Live" when real-time push updates are active; "Polling" when the interface falls back to checking for updates every 30 seconds
• Demo badge — an amber "DEMO" label shown when the server is running in demonstration mode with simulated data
• Notifications bell — count of recent toast events; click to review the list
• User menu — current persona badge; Disconnect / Clear session

Command Palette (Cmd+K / Ctrl+K)

Press Cmd+K on macOS or Ctrl+K on Windows/Linux from any page to open the Command Palette. It provides smart routing based on what you type:

Inspector Drawer

The right-side Inspector Drawer slides in when you click a device row in Device Inventory, a node in the Topology graph, or a rule row in Firewall Policies. It persists across page navigation until explicitly closed (× button or Escape).

For devices, the drawer shows six tabs:

Sidebar Navigation Groups

The left sidebar organises pages into seven sections:

7.2 Topology View (/topology)

The topology view renders a Cytoscape.js force-directed graph of all network devices and their connections.

Node Types & Colours

Interactions

• Click a node — opens the Inspector Drawer with the 6-tab device detail panel.
• Click an edge — shows the interfaces on each end that form the connection.
• Scroll / pinch — zoom the graph.
• Drag — pan the canvas or reposition nodes.
• Search bar — filters the graph by hostname; entering a name in focus mode triggers a 2-hop neighbourhood query.

Focus Mode (large networks)

When the graph contains more than 200 devices a Focus Mode button appears. Activating it switches to neighbourhood view: type a hostname and click Focus to load only the 2-hop subgraph around that device using the topology_neighborhood query. Click Exit Focus Mode to return to the full graph.

Topology Overlays

Both Blast Radius and Path Analysis pages offer an Overlay on Topology / Show path on Topology button after results are returned. Clicking it stores the result in memory and navigates to the Topology page, which applies the overlay automatically:

• Blast Radius overlay — impacted nodes highlighted in rose; non-impacted nodes dimmed; a dismissible banner shows the focal device and endpoint count.
• Path Analysis overlay — matched firewall nodes highlighted in emerald; a banner shows src → dst. Click Dismiss to clear.

7.3 Device Inventory (/devices)

A virtualized table of all collected network devices, supporting datasets of 10,000+ rows at 60 fps. Data is cached client-side for 5 minutes.

Filters

• Search — free-text match against hostname, vendor, and model
• Vendor — multi-select pill filter (Cisco, Juniper, Palo Alto, etc.)
• Has firewall rules — toggle to show only devices with collected firewall policies

Active filter count is shown on the Filters button; click Clear all inside the panel to reset.

Row Actions

• Click any row — opens the Inspector Drawer with the 6-tab device detail panel.
• Show in Topology — navigates to the Topology page and focuses the selected device.
• Export JSON — downloads the currently filtered device list as a JSON file.

Column Visibility

Click the Columns button (top-right of the table) to show or hide individual columns (Vendor, Model, OS Version, Serial, Collected At).

7.4 Endpoint Search (/endpoints)

Two modes are available via the toggle in the page header:

Search Mode

Locate a single host by IP address or MAC address.

• IP mode — accepts a single IPv4/IPv6 address or a CIDR prefix; an optional VRF field narrows results to a specific routing domain.
• MAC mode — accepts any standard MAC format (colon, hyphen, or dotted-quad).

The Command Palette auto-fills and fires a search when you type an IP or MAC and press Enter.

Inventory Mode

Loads all known endpoints (up to 10,000) into a virtualized table with the same column controls as Device Inventory. Click any row to open the Inspector Drawer.

Orphaned Endpoints

An expandable amber panel at the bottom of the page shows endpoints that have no associated subnet record — a sign that the IPAM configuration may be incomplete. Backed by the endpoints_without_location query.

7.5 Subnets & IP Schema (/subnets) analyst+

An IPAM-style view for exploring subnet allocations and tracking address hygiene. Requires analyst persona or higher.

Query Modes

Orphaned IPs

An expandable amber section runs the orphaned_ips query on first open and shows IPs that are configured on interfaces but do not belong to any known subnet definition. This is a common indicator of misconfiguration or missing subnet entries in the graph.

7.6 Firewall Policies (/firewall) security+

Displays a filterable, searchable table of all collected firewall rules across all devices.

Filters

• Device — filter by firewall hostname
• Zone pair — source zone / destination zone dropdowns
• Action — allow / deny / drop / reject
• Enabled — show only active or disabled rules
• Search — full-text search across rule name, zones, and address objects

Expanded Row

Click any rule row to expand the detail panel showing: source zones, destination zones, source addresses, destination addresses, services, protocols, ports, logging state, and rule comments. Click the row again to collapse.

Deny Rules Summary

The Deny Rules tab (or the deny_rules_summary query) shows all deny/drop/reject rules across every firewall — useful for quickly auditing what the perimeter explicitly blocks.

7.7 Path Analysis (/path-analysis) security+

Interactive source-to-destination path analysis through the firewall rule chain.

1. Enter the Source IP address.
2. Enter the Destination IP address.
3. Optionally enter Protocol (e.g. tcp) and Destination Port (e.g. 443).
4. Click Analyse Path.

Results display a PERMITTED (green) or DENIED (red) verdict banner, followed by a per-firewall breakdown of the first-matching rule, its action, rule name, and the zone pair that matched.

After results appear, click Show path on Topology to navigate to the Topology page with the matched firewall devices highlighted in emerald.

7.8 Blast Radius (/blast-radius)

Simulate the impact of losing a device, interface, VLAN, or subnet, and see the downstream endpoints that would be affected.

Query Types

After results are returned, click Overlay on Topology to navigate to the Topology page with impacted nodes highlighted in rose and a dismissible banner showing the focal device and endpoint count.

7.9 Change Center (/history)

Tracks network state over time using an in-memory ring buffer of up to 288 snapshots (24 hours at 5-minute intervals). Three tabs provide different views of change data.

Trend Charts tab

Live sparkline charts showing device count, endpoint count, and firewall rule count over time, updated via SSE.

Network Diff tab

Select two timestamps using the from/to date pickers and click Compare to call GET /history/diff. The response is presented as a three-column diff:

• Removed — devices or rules present in the earlier snapshot but absent in the later
• Unchanged — items present in both snapshots
• Added — items present in the later snapshot but absent in the earlier

What-If Simulation tab Pro+

Submit a proposed topology change and see its impact before making any modifications to the live network.

Two input modes are available:

• Fields mode — structured inputs for proposed device count and firewall rule count
• JSON mode — raw NetworkFacts textarea for submitting specific devices, interfaces, and firewall rules

Results show current vs. proposed counts with a delta card and a list of new device hostnames. The simulation banner reads SIMULATION — not live data to prevent confusion. The endpoint is rate-limited to 10 requests per minute; a cooldown timer is shown when the limit is reached.

7.10 Automation (/automation) network+

Export network data and trigger external system synchronisation. Requires the network persona or higher.

Ansible Dynamic Inventory

Download an Ansible-compatible inventory file via the GET /inventory/ansible endpoint.

• Select format: JSON (for ansible-inventory --list) or INI (legacy format)
• Click Download inventory.json (or .ini) — the file is fetched and saved to disk
• Devices are grouped by vendor; devices with collected firewall rules appear in the additional firewalls group

Expand Copy automation snippet to get a pre-filled curl command with your API key for use in CI pipelines or Ansible dynamic inventory scripts.

NetBox Sync Enterprise

The NetBox Sync card is displayed only when NETBOX_URL and NETBOX_TOKEN are configured. It shows the configured sync direction (push / pull / both) and provides a Dry Run Sync button that calls POST /admin/netbox/sync?dry_run=true and displays the proposed changes without committing them.

7.11 Admin (/admin) admin only

The Admin page is restricted to the admin persona. It provides five tabs for managing the running instance.

8.1 Authentication

All query endpoints require the X-API-Key HTTP header. Set the API key with the API_KEY environment variable at startup.

curl -H "X-API-Key: your-api-key" http://localhost:8000/queries/

A missing or invalid key returns 401 Unauthorized.

8.2 API Endpoints

/history/diff

Compare two network snapshots by timestamp and receive a structured diff of topology and firewall policy changes.

GET /history/diff?from_ts=2026-02-01T00:00:00Z&to_ts=2026-02-24T00:00:00Z
X-API-Key: your-api-key

# Response
{
  "from_ts": "2026-02-01T00:00:00Z",
  "to_ts": "2026-02-24T00:00:00Z",
  "devices_added": ["fw-dmz-02"],
  "devices_removed": [],
  "rules_added": ["fw-dmz-02:permit-80"],
  "rules_removed": ["fw-core-01:deny-8080"],
  "delta": {
    "devices": 1,
    "firewall_rules": 0
  }
}

/graph/whatif

Submit a partial NetworkFacts payload representing a proposed change. The API returns a comparison of the proposed state against the latest snapshot, including counts of new devices and firewall rules. Requires a Pro or Enterprise license and is rate-limited to 10 requests per minute.

POST /graph/whatif
Content-Type: application/json
X-API-Key: your-api-key

{
  "devices": [...],
  "interfaces": [...],
  "firewall_rules": [...]
}

# Response
{
  "proposed": {"devices": 21, "firewall_rules": 62},
  "current":  {"devices": 20, "firewall_rules": 58},
  "delta":    {"devices": 1,  "firewall_rules": 4},
  "new_devices": ["fw-dmz-new"],
  "new_firewall_rules": ["fw-dmz-new:deny-any", ...]
}

Execute Request Body

POST /queries/{name}/execute
Content-Type: application/json
X-API-Key: your-api-key

{
  "parameters": { "device": "sw-core-01" },
  "limit": 1000,
  "offset": 0,
  "output_format": "json"
}

8.3 Query Categories

Topology Queries

Endpoint Queries

Blast Radius Queries Advanced

Addressing Queries

Hygiene Queries

Inventory & Summary Queries

Firewall Queries

8.4 Pagination & Export

Pagination

# Page 1 (rows 0–99)
{"parameters": {}, "limit": 100, "offset": 0}

# Page 2 (rows 100–199)
{"parameters": {}, "limit": 100, "offset": 100}

# Response includes total count
{
  "total": 1843,
  "offset": 100,
  "limit": 100,
  "rows": [...]
}

CSV Export

curl -H "X-API-Key: $API_KEY" \
  http://localhost:8000/queries/all_devices/execute \
  -d '{"parameters": {}, "output_format": "csv"}' \
  -o devices.csv

The response is a streaming CSV with a Content-Disposition: attachment; filename="all_devices.csv" header.

9.1 Overview & Requirements

The MCP server connects directly to Neo4j or PostgreSQL using the same query files as the REST API. It runs as a stdio transport process — the AI client starts it as a subprocess and communicates over stdin/stdout. No HTTP server or port is required.

Install the MCP Extras

pip install "meshoptixiq-network-discovery[mcp]"

# Or with PostgreSQL support
pip install "meshoptixiq-network-discovery[postgres,mcp]"

Environment Variables (MCP)

Test the MCP Server

GRAPH_BACKEND=neo4j \
NEO4J_URI=bolt://localhost:7687 \
NEO4J_PASSWORD=your-password \
MESHOPTIXIQ_LICENSE_KEY=mq-prod-xxxxxxxxxx \
  meshq-mcp

The server will print its initialisation options to stderr and then wait for MCP protocol messages on stdin. Use Ctrl+C to stop.

9.2 Claude Desktop Setup

Add MeshOptixIQ to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Python Installation

{
  "mcpServers": {
    "meshoptixiq": {
      "command": "meshq-mcp",
      "env": {
        "GRAPH_BACKEND": "neo4j",
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your-password",
        "MESHOPTIXIQ_LICENSE_KEY": "mq-prod-xxxxxxxxxx"
      }
    }
  }
}

Docker

{
  "mcpServers": {
    "meshoptixiq": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--network", "host",
        "-e", "GRAPH_BACKEND=neo4j",
        "-e", "NEO4J_URI=bolt://localhost:7687",
        "-e", "NEO4J_PASSWORD=your-password",
        "-e", "MESHOPTIXIQ_LICENSE_KEY=mq-prod-xxxxxxxxxx",
        "meshoptixiq/discovery-agent:latest",
        "meshq-mcp"
      ]
    }
  }
}

Restart Claude Desktop after editing the config. MeshOptixIQ should appear in the tool panel (plug icon).

9.3 Claude Code Setup

Add MeshOptixIQ as an MCP server in your Claude Code project:

# In your project directory
claude mcp add meshoptixiq meshq-mcp \
  --env GRAPH_BACKEND=neo4j \
  --env NEO4J_URI=bolt://localhost:7687 \
  --env NEO4J_PASSWORD=your-password \
  --env MESHOPTIXIQ_LICENSE_KEY=mq-prod-xxxxxxxxxx

Or add it globally (available in all projects):

claude mcp add --global meshoptixiq meshq-mcp \
  --env MESHOPTIXIQ_LICENSE_KEY=mq-prod-xxxxxxxxxx \
  --env NEO4J_PASSWORD=your-password

9.4 Available Tools, Resources & Prompts

Tools (23 total)

Resources (6 total)

Resources expose read-only network data as background context for AI reasoning.

Prompts (6 pre-defined templates)

Example Conversations

User: "What would be the impact if sw-core-01 went offline right now?"

Claude: [calls meshq_blast_radius_device with device="sw-core-01"]
        [calls meshq_topology_device_neighbors with device_name="sw-core-01"]
        "If sw-core-01 went offline, 847 endpoints would lose connectivity,
         distributed across VLANs 10, 20, and 100. Three distribution
         switches — sw-dist-01, sw-dist-02, and sw-dist-03 — would lose
         their uplink. I recommend scheduling maintenance in a 2-hour window
         outside business hours..."

10.1 Production Docker Compose

The following Docker Compose configuration runs MeshOptixIQ, Neo4j, and an Nginx reverse proxy with automatic restarts and persistent volumes.

version: '3.8'

services:
  neo4j:
    image: neo4j:5-community
    restart: unless-stopped
    volumes:
      - neo4j-data:/data
      - neo4j-logs:/logs
    environment:
      NEO4J_AUTH: neo4j/${NEO4J_PASSWORD}
      NEO4J_PLUGINS: '["apoc"]'
      NEO4J_dbms_memory_heap_initial__size: 1G
      NEO4J_dbms_memory_heap_max__size: 4G
    healthcheck:
      test: ["CMD", "neo4j", "status"]
      interval: 30s
      timeout: 10s
      retries: 5

  meshoptixiq:
    image: meshoptixiq/discovery-agent:latest
    restart: unless-stopped
    depends_on:
      neo4j:
        condition: service_healthy
    ports:
      - "127.0.0.1:8000:8000"
    environment:
      GRAPH_BACKEND: neo4j
      NEO4J_URI: bolt://neo4j:7687
      NEO4J_USER: neo4j
      NEO4J_PASSWORD: ${NEO4J_PASSWORD}
      MESHOPTIXIQ_LICENSE_KEY: ${MESHOPTIXIQ_LICENSE_KEY}
      API_KEY: ${API_KEY}
      CORS_ORIGINS: https://meshoptixiq.yourdomain.com
    volumes:
      - meshoptixiq-cache:/app/cache
      - ./inventory.yaml:/app/configs/inventory.yaml:ro
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 5s
      retries: 3

  nginx:
    image: nginx:alpine
    restart: unless-stopped
    depends_on:
      - meshoptixiq
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./nginx/certs:/etc/nginx/certs:ro

volumes:
  neo4j-data:
  neo4j-logs:
  meshoptixiq-cache:

Store secrets in a .env file (never committed to version control):

NEO4J_PASSWORD=strong-random-password-here
MESHOPTIXIQ_LICENSE_KEY=mq-prod-xxxxxxxxxx
API_KEY=strong-random-api-key-here

# Start the stack
docker compose --env-file .env up -d

# View logs
docker compose logs -f meshoptixiq

# Run collection inside the container
docker compose exec meshoptixiq meshq collect \
  --source /app/configs/inventory.yaml

10.2 PostgreSQL Backend

Switch to PostgreSQL by setting GRAPH_BACKEND=postgres and providing a POSTGRES_DSN. The PostgreSQL schema is created automatically on first ingest.

services:
  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_DB: meshoptixiq
      POSTGRES_USER: meshoptixiq
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres-data:/var/lib/postgresql/data

  meshoptixiq:
    image: meshoptixiq/discovery-agent:latest
    environment:
      GRAPH_BACKEND: postgres
      POSTGRES_DSN: postgresql://meshoptixiq:${POSTGRES_PASSWORD}@postgres:5432/meshoptixiq
      MESHOPTIXIQ_LICENSE_KEY: ${MESHOPTIXIQ_LICENSE_KEY}
      API_KEY: ${API_KEY}

10.3 Reverse Proxy & TLS

Always front the MeshOptixIQ API with a reverse proxy that terminates TLS in production. A minimal Nginx config:

server {
    listen 443 ssl;
    server_name meshoptixiq.yourdomain.com;

    ssl_certificate     /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    # Security headers
    add_header Strict-Transport-Security "max-age=31536000" always;
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;

    location / {
        proxy_pass         http://127.0.0.1:8000;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_read_timeout 60s;
    }
}

# Redirect HTTP → HTTPS
server {
    listen 80;
    server_name meshoptixiq.yourdomain.com;
    return 301 https://$host$request_uri;
}

11.1 Installation & Startup Issues

API reports 503 on /health/ready

Cause: The graph backend (Neo4j or PostgreSQL) is not reachable.

1. Verify the database process is running: docker compose ps neo4j
2. Test the Bolt connection from the MeshOptixIQ host: nc -zv <neo4j-host> 7687
3. Check the NEO4J_URI variable — use bolt:// not http:// for the Bolt protocol
4. Verify the Neo4j credentials: NEO4J_USER / NEO4J_PASSWORD
5. Check Neo4j logs: docker compose logs neo4j

Web UI shows a blank page / 404

Cause: The UI_DIR path does not contain the built React app.

• In Docker: UI_DIR defaults to /app/static — verify the container was built correctly.
• In bare-metal: Set UI_DIR to the directory containing the Vite build output (dist/).

meshq command not found

• Ensure the package is installed: pip show meshoptixiq-network-discovery
• Verify the Python bin directory is in $PATH: which meshq || python3 -m network_discovery.cli version

11.2 License Issues

License not found

No license key found. Please set MESHOPTIXIQ_LICENSE_KEY
or create ~/.meshoptixiq/license.key

Set the environment variable or create the license file as described in §3.3.

License expired

LicenseExpiredError: License has expired.

Renew at meshoptixiq.com/pricing or via the customer portal at portal.meshoptixiq.com.

Device limit exceeded

LicenseDeviceMismatchError: Device limit exceeded for this license

Your Pro license allows up to 5 registered installation hosts. To transfer a registration or add seats, contact hello@meshoptixiq.com.

Grace period active

Running in grace period. 48.3 hours remaining.

The licensing server was not reachable during the last 24-hour check. Ensure api.meshoptixiq.com:443 (HTTPS) is accessible from the host. The application will continue working for 72 hours from the last successful validation.

Feature not available

FeatureNotAvailableError: Feature 'advanced_queries' is not available
on the 'starter' plan. Upgrade to 'pro' or higher.

Upgrade your plan at meshoptixiq.com/pricing.

11.3 Collection Failures

SSH connection refused / timeout

Collection failed for sw-core-01: SSH connection timed out

1. Verify the device is reachable: ping <device-ip>
2. Test SSH directly: ssh -v <username>@<device-ip> -p 22
3. Check that TCP/22 is allowed through any intermediate firewalls between the MeshOptixIQ host and the device
4. Increase the timeout in the inventory file: timeout: 60

Authentication failure

Authentication failed for sw-core-01: Invalid credentials

• Verify the username and password in the inventory file or environment variables
• Confirm the account has SSH access and the necessary show-command privileges
• For devices requiring enable mode, add secret: "{{ env.ENABLE_SECRET }}" to the device definition

Parser produced zero results

If meshq parse reports 0 interfaces or 0 endpoints for a device:

• Check the raw cache: cat ~/.meshoptixiq/cache/<hostname>/*.txt
• Ensure the device_type in the inventory file matches the actual device OS
• Confirm the device returns expected output for commands like show interfaces and show ip arp

11.4 Query & API Errors

400 Bad Request — Missing parameters

{"detail": "Missing parameters: ['device_name']"}

Include all required parameters in the parameters object. Check the query schema with GET /queries/{name}.

401 Unauthorized

The X-API-Key header is missing or the value does not match the API_KEY environment variable.

404 Not Found — Query not found

The query name in the URL is misspelled. Use GET /queries/ to list all valid query names.

500 Internal Server Error on query execution

• Check FastAPI logs: docker compose logs meshoptixiq
• Verify the graph backend is reachable: GET /health/ready
• Ensure data has been ingested: run the full collection pipeline and then retry

MCP server exits immediately

ERROR: MCP server requires a pro or enterprise license.

Set MESHOPTIXIQ_LICENSE_KEY to a valid Pro or Enterprise key. Starter keys will not start the MCP server.

12.1 Secret Management

Recommended Secret Storage

12.2 Network Security

• Always run behind a reverse proxy with TLS. The FastAPI process itself does not terminate TLS. Use Nginx, Caddy, or a load balancer in front of port 8000.
• Restrict CORS. Set CORS_ORIGINS to your specific UI origin rather than leaving it as *.
• Bind to loopback. In Docker Compose, publish as 127.0.0.1:8000:8000 so only the reverse proxy can reach the FastAPI process.
• Firewall the database. Neo4j's Bolt port (7687) and PostgreSQL (5432) should only be accessible from the MeshOptixIQ host — never exposed to the public internet.
• Segment the collector. The host running meshq collect needs SSH access to network devices. Place it on a dedicated management VLAN with strict ACLs.

12.3 SSH Credential Security

• Create a dedicated read-only service account on each network device for MeshOptixIQ. Grant only the minimum commands required (show interfaces, show arp, show mac address-table, show ip route).
• Prefer SSH key authentication over passwords. Store private keys at ~/.ssh/meshoptixiq_ed25519 with chmod 600.
• Rotate SSH credentials periodically and update the inventory file accordingly.
• Disable password authentication on devices if SSH keys are in use.

12.4 API Key Hardening

• Generate a strong random API key: openssl rand -hex 32 (64 hex characters)
• Rotate the API key periodically. Rolling restarts with the new key ensure zero-downtime rotation.
• Log all API requests. The FastAPI middleware logs method, path, status code, and latency for each request.
• Consider adding a WAF (Web Application Firewall) in front of the API for production deployments.

12.5 Keeping Current

• Subscribe to security advisories at github.com/meshoptixiq/meshoptixiq/security/advisories.
• Update the Docker image regularly: docker pull meshoptixiq/discovery-agent:latest.
• Monitor the PYTHONPATH dependencies for CVEs using pip audit in development environments.
• Neo4j and PostgreSQL should run the latest patch release of their major version.

13.1 Enterprise Container Image

Enterprise images are published alongside the standard image with an enterprise- version prefix:

# Pull latest enterprise image
docker pull meshoptixiq/discovery-agent:enterprise-latest

# Or pin to a specific release
docker pull meshoptixiq/discovery-agent:enterprise-1.3.0

Startup Sequence

The enterprise container runs a Python entrypoint (/app/entrypoint.py) before starting the API server. The entrypoint:

1. Reads SECRETS_PROVIDER to determine which secrets backend to use.
2. Fetches secrets from the configured backend and merges them into the process environment.
3. Replaces itself with uvicorn via os.execvpe — uvicorn runs as PID 1 with all secrets injected as environment variables. No secrets are stored on disk.

Minimal Quickstart

docker run -d \
  -e NEO4J_URI=bolt://neo4j:7687 \
  -e NEO4J_PASSWORD=your-password \
  -e MESHOPTIXIQ_LICENSE_KEY=mq-ent-xxxxxxxxxx \
  -e API_KEY=your-api-key \
  -p 8000:8000 \
  meshoptixiq/discovery-agent:enterprise-latest

13.2 Secrets Management

Set SECRETS_PROVIDER to pull credentials from an external secrets store at startup. The fetched values are merged into the container environment before uvicorn starts, so all application config (database passwords, API keys, license keys) can be stored securely in your vault.

Secrets in all backends must be stored as a JSON object mapping environment variable names to values:

{"API_KEY": "...", "NEO4J_PASSWORD": "...", "MESHOPTIXIQ_LICENSE_KEY": "..."}

HashiCorp Vault

SECRETS_PROVIDER=vault
VAULT_ADDR=https://vault.corp.local:8200
VAULT_SECRET_PATH=secret/data/meshoptixiq   # KV v2 path

AWS Secrets Manager

SECRETS_PROVIDER=aws
AWS_SECRET_NAME=prod/meshoptixiq    # Secret name
AWS_REGION=us-east-1                # Defaults to us-east-1

Authentication uses the standard AWS credential chain: IAM instance profile, ECS task role, AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY, or ~/.aws/credentials.

Azure Key Vault

SECRETS_PROVIDER=azure
AZURE_KEY_VAULT_URL=https://myvault.vault.azure.net
AZURE_SECRET_NAMES=meshoptixiq-secrets          # Comma-separated list of secret names

Authentication uses DefaultAzureCredential (managed identity, environment, or CLI). If a secret value is valid JSON it is unpacked into multiple env vars; otherwise the whole value is stored under the uppercased, hyphen-to-underscore secret name.

GCP Secret Manager

SECRETS_PROVIDER=gcp
GCP_PROJECT_ID=my-project
GCP_SECRET_IDS=meshoptixiq-secrets:latest   # Comma-separated name:version pairs

Omit the version suffix to default to latest. Authentication uses Application Default Credentials (Workload Identity, GOOGLE_APPLICATION_CREDENTIALS, or gcloud auth).

13.3 Enterprise Authentication (OIDC)

By default MeshOptixIQ uses a single shared X-API-Key header. The enterprise image adds OIDC/JWT Bearer token authentication via the AUTH_MODE environment variable.

OIDC Configuration

# Required when AUTH_MODE=oidc or AUTH_MODE=both
AUTH_MODE=both
OIDC_DISCOVERY_URL=https://company.okta.com/.well-known/openid-configuration
OIDC_CLIENT_ID=meshoptixiq-api-client

# Optional: comma-separated list of scopes every token must contain
OIDC_REQUIRED_SCOPES=read:queries

On startup the API fetches the OIDC discovery document to locate the JWKS endpoint, then caches the JSON Web Key Set (JWKS) for one hour. Key rotation is handled automatically: if a token's kid is not in the cache, the JWKS is immediately refreshed before re-validating.

Token Validation

Every Bearer token is validated for:

• Signature — verified against the JWKS public keys.
• Expiry (exp) — expired tokens receive 401 Unauthorized.
• Issuer (iss) — must match the OIDC discovery URL base.
• Audience (aud) — must match OIDC_CLIENT_ID.
• Required scopes — if OIDC_REQUIRED_SCOPES is set, all listed scopes must be present; missing scopes return 403 Forbidden.

On successful validation, a UserContext object (containing sub, email, roles, groups, scopes) is attached to request.state.user and made available to audit logging.

13.4 Audit Logging & SIEM

Set AUDIT_LOG_ENABLED=true to emit a structured audit event after every request to /queries/* endpoints. Events are shipped simultaneously to all configured targets.

Audit Event Schema

{
  "event":       "query_executed",
  "timestamp":   "2026-02-22T10:30:00Z",
  "request_id":  "uuid-v4",
  "client_ip":   "10.0.0.1",
  "user":        "alice@corp.com",       // JWT sub or "api_key_client"
  "method":      "POST",
  "path":        "/queries/topology_summary/execute",
  "query_name":  "topology_summary",
  "status":      200,
  "row_count":   42,
  "elapsed_ms":  85.3
}

Shipping Targets

Splunk Example

AUDIT_LOG_ENABLED=true
SPLUNK_HEC_URL=https://splunk.corp.local:8088/services/collector/event
SPLUNK_HEC_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
SPLUNK_INDEX=network-audit

Elasticsearch Example

AUDIT_LOG_ENABLED=true
ELASTICSEARCH_URL=https://elastic.corp.local:9200
ELASTICSEARCH_API_KEY=base64-encoded-api-key
ELASTICSEARCH_INDEX=meshoptixiq-audit

13.5 Observability

The enterprise image activates APM tracing by detecting known exporter environment variables. Backends are tried in priority order; only the first match is activated.

Datadog

DD_AGENT_HOST=datadog-agent    # Hostname of the Datadog agent
DD_SERVICE=meshoptixiq          # Service name in Datadog APM (default: meshoptixiq)
DD_ENV=production               # Environment tag
DD_VERSION=1.3.0                # Version tag

New Relic

NEW_RELIC_LICENSE_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
NEW_RELIC_APP_NAME=MeshOptixIQ (default: meshoptixiq)

OpenTelemetry (OTLP)

The OTLP exporter is compatible with any OTel Collector, including Datadog in OTLP mode, New Relic OTLP ingest, Grafana Tempo, Jaeger, and Splunk Observability.

OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
OTEL_SERVICE_NAME=meshoptixiq
OTEL_TRACES_EXPORTER=otlp    # Set to "none" to disable span export while keeping the SDK