Illumio MCP Server

A Model Context Protocol (MCP) server that provides an interface to interact with Illumio PCE (Policy Compute Engine). This server enables programmatic access to Illumio workload management, label operations, traffic flow analysis, automated ringfencing, and infrastructure service identification.

What can it do?

Use conversational AI to talk to your PCE:

• Full CRUD on workloads, labels, IP lists, services, and rulesets
• Traffic analysis — query flows, get summaries, filter by policy decision
• Automated ringfencing — analyze traffic and create app-to-app segmentation policies with one command
• Selective enforcement — add deny rules for apps in selective mode with configurable consumer flavors
• Infrastructure service identification — discover which apps are infrastructure services using graph centrality analysis, so you know what to policy first
• Deny rule management — create, update, and delete deny rules (including override deny for emergencies)
• Event monitoring — query PCE events with severity and type filters
• PCE health checks — verify connectivity and credentials

Prerequisites

• Python 3.8+
• Access to an Illumio PCE instance
• Valid API credentials for the PCE

Installation

1. Clone the repository:

git clone https://github.com/alexgoller/illumio-mcp-server.git
cd illumio-mcp-server

2. Install dependencies:

uv sync

Configuration

You should run this using the uv command, which makes it easier to pass in environment variables and run it in the background.

Using uv and Claude Desktop

On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

Add the following to the custom_settings section:

"mcpServers": {
    "illumio-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/illumio-mcp-server",
        "run",
        "illumio-mcp"
      ],
      "env": {
        "PCE_HOST": "your-pce-host",
        "PCE_PORT": "your-pce-port",
        "PCE_ORG_ID": "1",
        "API_KEY": "api_key",
        "API_SECRET": "api_secret"
      }
    }
  }
}

HTTP transport with OAuth Resource Server (Phase 3a)

The server runs over HTTP using the MCP Streamable HTTP transport (spec rev 2025-03-26) and validates OAuth 2.1 bearer tokens issued by your IdP. This is Phase 3a: identity is enforced; per-user PCE keys land in Phase 3b.

Running with auth (production-shaped)

export MCP_PUBLIC_URL=https://mcp.illumio.example
export MCP_OAUTH_ISSUER=https://login.microsoftonline.com/<tenant-id>/v2.0
export MCP_OAUTH_JWKS_URL=https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys
export MCP_OAUTH_AUDIENCE=https://mcp.illumio.example
export MCP_OAUTH_REQUIRED_SCOPE=illumio-mcp.use   # default; override if needed
illumio-mcp-http --host 127.0.0.1 --port 8080

The server refuses to start without these env vars (unless MCP_DEV_INSECURE=1).

MCP clients discover the AS via the standard RFC 9728 endpoint:

GET /.well-known/oauth-protected-resource

Unauthenticated requests to /mcp return 401 with WWW-Authenticate: Bearer resource_metadata="<URL>", which any spec-compliant MCP client (Claude Desktop, ChatGPT, MCP Inspector) follows automatically to run PKCE auth code flow against the configured AS.

Running without auth (dev only)

MCP_DEV_INSECURE=1 illumio-mcp-http

The server logs a prominent warning. Do NOT use in production.

Health endpoints (always unauthenticated)

• GET /healthz — liveness
• GET /readyz — readiness (Phas

... View full README on GitHub