Illumio MCP Server

get-iplists

Retrieve IP lists from the PCE with optional filters, including exact address containment checks, to identify which lists cover a given IPv4 or IPv6 address.

Instructions

Get IP lists from the PCE with optional filtering. Each list carries ip_ranges as [{from_ip, to_ip, exclusion, description}] and fqdns as [{fqdn, description}], plus is_default: true on the built-in list that covers 0.0.0.0/0 or ::/0. Use contains_ip for an exact 'which lists cover this address' answer, evaluated server-side (CIDRs, from/to spans, exclusions, IPv4 and IPv6); the ip_address filter is the PCE's substring match on the range text and does not look inside CIDRs.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "get-iplists"
  }
}

Input Schema

Name	Required	Description
`fqdn`	No	Filter by FQDN (supports partial matches)
`name`	No	Filter IP lists by name (supports partial matches)
`pversion`	No	Policy version to read (default draft). Echoed as policy_version in the response.
`ip_address`	No	PCE-side substring match on the range text (e.g. '10.20.30.4' matches '10.20.30.40/32' and never matches an address inside a CIDR). Use contains_ip for exact containment.
`contains_ip`	No	A single IPv4 or IPv6 address. Return only the IP lists whose ranges contain it, honouring exclusion ranges; each returned list carries matched_range. Combine with is_default to tell 'in a real list' from 'only in Any'.
`description`	No	Filter by description (supports partial matches)
`max_results`	No	Maximum number of IP lists to return

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.13.0Oct 31, 2026

addedInput schema / properties / contains_ip

Added value: +{
+  "description": "A single IPv4 or IPv6 address. Return only the IP lists whose ranges contain it, honouring exclusion ranges; each returned list carries matched_range. Combine with is_default to tell 'in a real list' from 'only in Any'.",
+  "type": "string"
+}

changedInput schema / properties / ip_address / description

Previous value: -"Filter by IP address (supports partial matches)"New value: +"PCE-side substring match on the range text (e.g. '10.20.30.4' matches '10.20.30.40/32' and never matches an address inside a CIDR). Use contains_ip for exact containment."

addedInput schema / properties / pversion

Added value: +{
+  "description": "Policy version to read (default draft). Echoed as policy_version in the response.",
+  "enum": [
+    "draft",
+    "active"
+  ],
+  "type": "string"
+}

Changed6 schema fields changedv0.8.0Sep 18, 2026

changedInput schema / properties / description / description

Previous value: -"Filter by description (optional)"New value: +"Filter by description (supports partial matches)"

addedInput schema / properties / fqdn

Added value: +{
+  "description": "Filter by FQDN (supports partial matches)",
+  "type": "string"
+}

addedInput schema / properties / ip_address

Added value: +{
+  "description": "Filter by IP address (supports partial matches)",
+  "type": "string"
+}

removedInput schema / properties / ip_ranges

Removed value: -{
-  "description": "Filter by IP ranges (optional)",
-  "items": {
-    "type": "string"
-  },
-  "type": "array"
-}

addedInput schema / properties / max_results

Added value: +{
+  "description": "Maximum number of IP lists to return",
+  "type": "integer"
+}

changedInput schema / properties / name / description

Previous value: -"Filter IP lists by name (optional)"New value: +"Filter IP lists by name (supports partial matches)"

Addedv1.0.0Jan 2, 2026

TDQS

A4.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden; it discloses the returned shape (ip_ranges, fqdns, is_default on the 0.0.0.0/0 or ::/0 list), that containment is evaluated server-side across CIDRs, spans, exclusions and both IP families. It stops short of stating read-only safety explicitly or pagination/limits behavior beyond the max_results parameter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then return shape, then the filtering semantics that matter most. Dense but every clause carries information; the final sentence is long but is the single most decision-relevant sentence in the description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no annotations, the description supplies the return structure (ip_ranges with from_ip/to_ip/exclusion/description, fqdns, is_default, matched_range) and the filter semantics an agent needs. Nothing critical for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so baseline is 3; the description adds real meaning by explaining the semantic gap between contains_ip (exact containment, honours exclusions, returns matched_range) and ip_address (substring on range text, never matches inside a CIDR). It also explains is_default, which is not a parameter but shapes filtering strategy.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get IP lists from the PCE'), adds scope ('optional filtering'), and distinguishes itself from the address-containment query path. An agent can tell it apart from siblings like create-iplist/update-iplist without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: use contains_ip for an exact 'which lists cover this address' answer, while ip_address is only a substring match on range text. It also explains how to combine contains_ip with is_default to separate 'in a real list' from 'only in Any'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server