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.

<a href="https://glama.ai/mcp/servers/xhqzxlo9iy">

</a>

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 (Phase 3a returns the same as healthz; Phase 3b/c will add PCE + JWKS reachability)

Two PCE modes (Phase 3b vs Phase 3e)

The HTTP server supports two ways to source PCE credentials, selected via
MCP_PCE_MODE:

| Mode | MCP_PCE_MODE | PCE creds | Onboarding | PCE-side audit |
|---|---|---|---|---|
| Per-user (default) | per_user | One PCE API key per authenticated user, encrypted in keystore | User registers via /setup page or register-pce-credentials tool | PCE logs show the real human via per-user API key |
| Shared | shared | One PCE service-account key from env (same as stdio) | None — works immediately for any authenticated user | PCE logs show the service account; the MCP audit log is the source of truth for "who did what" |

Choose per-user when:
- You want PCE-side audit attribution to identify the human
- Users are happy to provide their own PCE API key once
- You can tolerate the per-user PCE key sprawl (PCE has limits)

Choose shared when:
- The PCE limits API keys per user too aggressively for per-user mode
- You want zero-friction onboarding (no /setup step)
- You're OK relying on the MCP audit log alone for human-level attribution
- You operate the PCE service account yourself and rotate it on a schedule

In shared mode, /setup is not mounted, the credential-management tools
(register-pce-credentials, delete-pce-credentials) refuse with a friendly
error, and MCP_KEK is not required. SSO + JWT + role-based authz + audit
log + confirm tokens all still apply identically.

```bash