Skip to content

Machine setup from zero — Windows & macOS

This guide takes a brand-new machine to a working iiq-rules-mcp server inside Claude Desktop: Python, uv, a JDK, the server itself, and your first grounded session. Nothing is assumed pre-installed.

Time budget: 20–30 minutes, most of it downloads.

When you're done here, continue with the HOW-TO guide for the authoring workflow, verdict semantics, and the full troubleshooting table.

What you'll install, and why

Component Why the server needs it
uv installs and runs the server in its own isolated environment; also manages Python for you
Python 3.11+ the server is a Python application (uv fetches this — no separate installer needed)
JDK 17+ (11 minimum, enforced at boot) the server starts a JVM to reflect over your identityiq.jar and to run the BeanShell parser
Claude Desktop the MCP client you'll author rules in (any stdio MCP client works)
Your licensed IIQ artifacts the ground truth: identityiq.jar, the full WEB-INF/lib, sailpoint.dtd, optional object export
iiq-rules-mcp wheel the server — from the Releases page, or the .whl file shared with you

Part A — Windows (10 / 11)

All commands run in PowerShell (Start → type "powershell"). No administrator rights are needed except possibly for the JDK installer.

A1. Install uv

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Close PowerShell and open a new one (the installer updates PATH for new shells only), then verify:

uv --version

✅ Prints a version like uv 0.5.x or newer.

A2. Install Python (via uv — no separate installer)

uv python install 3.12

✅ Prints Installed Python 3.12.x. That's it — uv keeps this Python in its own managed location and uses it automatically. You do not need the python.org installer or the Microsoft Store version.

If you prefer a system-wide Python instead, the python.org installer works too — tick "Add python.exe to PATH" during install. Either way, 3.11 is the floor.

Temurin is OpenJDK — a free, GPL-licensed build with a proper installer and long-term updates. Any OpenJDK distribution works equally (Amazon Corretto, Azul Zulu, Microsoft Build of OpenJDK); the Oracle-branded JDK also works but carries Oracle's own license terms, which enterprise compliance teams may ask about.

Option 1 — winget (built into Windows 11; on Windows 10 update "App Installer" from the Store first):

winget install EclipseAdoptium.Temurin.21.JDK

Option 2 — download the .msi from https://adoptium.net (Temurin 21 LTS, x64). During install, enable the "Set JAVA_HOME variable" feature — it makes JVM discovery automatic.

Open a new PowerShell and verify:

java -version

✅ Prints openjdk version "21...". Any JDK 17+ from any vendor is fine; 11 is the hard floor (the server refuses to boot below it). Newer JDKs (e.g. 25) also work — you may see harmless "restricted method" warnings in the logs.

A4. Install Claude Desktop

Download from https://claude.ai/download, install, and sign in once.

A5. Copy your IIQ artifacts onto the machine

From your licensed IIQ installation (sandbox VM, deployment, or build tree), copy — keeping the folder structure simple:

C:\iiq\WEB-INF\lib\          <- the WHOLE lib folder (identityiq.jar, bsh.jar, everything)
C:\iiq\WEB-INF\lib-connectors\   <- if your install has it
C:\iiq\sailpoint.dtd         <- generated from the IIQ console (see below)
C:\iiq\exports\objects.xml   <- optional: generated from the IIQ console (see below)

Generate the DTD and the export on your IIQ host with iiq console (the launcher is in WEB-INF/bin; Windows: iiq.bat) — so the DTD matches your exact build:

> dtd C:\temp\sailpoint.dtd
dtd written to "C:\temp\sailpoint.dtd"
> export -clean C:\temp\objects.xml
> quit

Two rules that save an hour of debugging later: copy the entire WEB-INF/lib (the jar alone is not enough — boot will refuse and name bsh.jar), and generate the DTD from the same install as the jar (a mismatched DTD is the classic cause of pins_ok: false). The HOW-TO guide has the full console walkthrough.

A6. Install the MCP server

With the wheel file downloaded (from the Releases page, or shared with you directly):

uv tool install --from "C:\path\to\iiq_rules_mcp-1.6.4-py3-none-any.whl" iiq-rules-mcp

✅ Ends with Installed 2 executables: iiq-rules-activate, iiq-rules-mcp.

Sanity check — both of these "failing" politely is CORRECT at this point:

iiq-rules-mcp            # expect: "ERROR: no IIQ JAR(s) configured" (config comes next)
iiq-rules-activate status # expect: mode "unlicensed" (trial comes at the end)

A7. Configure Claude Desktop

In Claude Desktop: Settings → Developer → Edit Config. This opens claude_desktop_config.json. Make it look like this (merge into mcpServers if the file already has content) — note the doubled backslashes and the ; separator between lib directories:

{
  "mcpServers": {
    "iiq-rules-mcp": {
      "command": "iiq-rules-mcp",
      "env": {
        "IIQ_JAR_PATH": "C:\\iiq\\WEB-INF\\lib\\identityiq.jar",
        "IIQ_LIB_DIRS": "C:\\iiq\\WEB-INF\\lib;C:\\iiq\\WEB-INF\\lib-connectors",
        "IIQ_DTD_PATH": "C:\\iiq\\sailpoint.dtd",
        "IIQ_OBJECTS_EXPORT": "C:\\iiq\\exports\\objects.xml"
      }
    }
  }
}

Omit the IIQ_OBJECTS_EXPORT line if you have no export — everything else still works, and the affected checks label themselves honestly.

Save, then fully quit Claude Desktop from the system tray (right- click the tray icon → Quit — closing the window is NOT enough) and relaunch it.

A8. Verify → skip to "First session" below

Part B — macOS (Apple Silicon or Intel)

All commands run in Terminal (⌘-Space → "Terminal").

B1. Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Open a new Terminal window (or run the source line the installer prints), then verify:

uv --version

✅ Prints a version like uv 0.5.x or newer.

B2. Install Python (via uv)

uv python install 3.12

✅ Prints Installed Python 3.12.x. No python.org installer or Homebrew Python needed — uv manages it.

Temurin is OpenJDK (see the note in A3 — any OpenJDK build works).

Option 1 — download the .pkg from https://adoptium.net (Temurin 21 LTS; pick aarch64 for Apple Silicon, x64 for Intel) and run it.

Option 2 — if you already use Homebrew:

brew install --cask temurin@21

Verify in a new Terminal:

java -version
/usr/libexec/java_home

✅ First prints openjdk version "21..."; second prints the JDK path (remember it — useful if the server ever needs IIQ_JVM_PATH).

B4. Install Claude Desktop

Download from https://claude.ai/download, drag to Applications, sign in.

B5. Copy your IIQ artifacts onto the machine

Same rules as Windows — whole WEB-INF/lib, and generate the DTD (and optional export) from ./iiq console on the IIQ host so the DTD matches your build:

> dtd /var/tmp/sailpoint.dtd
dtd written to "/var/tmp/sailpoint.dtd"
> export -clean /var/tmp/objects.xml
> quit

Then copy the generated files over, e.g.:

/Users/<you>/iiq/WEB-INF/lib/
/Users/<you>/iiq/WEB-INF/lib-connectors/
/Users/<you>/iiq/sailpoint.dtd
/Users/<you>/iiq/exports/objects.xml    (optional)

Use your real username — write paths out in full (the config file does not expand ~ reliably across clients).

B6. Install the MCP server

uv tool install --from ~/Downloads/iiq_rules_mcp-1.6.4-py3-none-any.whl iiq-rules-mcp

✅ Ends with Installed 2 executables: iiq-rules-activate, iiq-rules-mcp.

Sanity check (polite failures = correct):

iiq-rules-mcp             # expect: "ERROR: no IIQ JAR(s) configured"
iiq-rules-activate status # expect: mode "unlicensed"

B7. Configure Claude Desktop

Settings → Developer → Edit Config, then — note the : separator (not ;) and forward slashes:

{
  "mcpServers": {
    "iiq-rules-mcp": {
      "command": "iiq-rules-mcp",
      "env": {
        "IIQ_JAR_PATH": "/Users/<you>/iiq/WEB-INF/lib/identityiq.jar",
        "IIQ_LIB_DIRS": "/Users/<you>/iiq/WEB-INF/lib:/Users/<you>/iiq/WEB-INF/lib-connectors",
        "IIQ_DTD_PATH": "/Users/<you>/iiq/sailpoint.dtd",
        "IIQ_OBJECTS_EXPORT": "/Users/<you>/iiq/exports/objects.xml"
      }
    }
  }
}

Save, fully quit Claude Desktop (⌘Q, or menu bar → Quit — not just closing the window) and relaunch it.

First session (both platforms)

1. Verify the grounding

In a new Claude Desktop chat, ask:

Run iiq_grounding_status and summarize it.

What green looks like:

  • grounding.iiq_version shows your build (e.g. 8.1 ...)
  • attestation.markers_ok: true — sailpoint.object.Identity, sailpoint.object.Rule, and bsh.Parser all loaded from YOUR jars
  • pins_ok: true — your jar, DTD, and export agree structurally
  • degradations: [] — or a named list of exactly what's missing

2. Start your free 7-day trial (no card)

Back in the terminal:

iiq-rules-activate trial --email you@example.com

✅ "trial active until " — and tools now answer with verdicts.

3. Author your first rule

Continue with the HOW-TO guide — the authoring loop, a 15-prompt library covering the common rule types, how to read the gate's verdicts, and what confirmed does (and does not) mean.

If something goes wrong

The server's design rule is refuse loudly, name the fix. Find the log via Claude Desktop (Settings → Developer → the iiq-rules-mcp entry → Logs) and match the message:

Message / symptom Fix
tools never appear in the chat you didn't FULLY quit the client — quit from the tray (Windows) / ⌘Q (macOS) and relaunch
no IIQ JAR(s) configured the env block is missing or in the wrong server entry — recheck A7/B7
configuration invalid naming a path a typo'd path — this fail-fast is deliberate; fix the path
JVM startup failed add "IIQ_JVM_PATH" to the env block: Windows → C:\\Program Files\\Eclipse Adoptium\\jdk-21...\\bin\\server\\jvm.dll; macOS → <java_home>/lib/server/libjvm.dylib
BOOT REFUSED ... bsh.Parser ... WEB-INF/lib you copied only the jar — point IIQ_LIB_DIRS at the FULL WEB-INF/lib
Java version refused JDK is below 11 — install 17+ (A3/B3)
pins_ok: false on every answer jar / DTD / export come from different releases — re-copy all from ONE install
license shows unlicensed and tools refuse run the trial command (First session, step 2)

Still stuck? The full troubleshooting table lives in the HOW-TO guide, and support is contact@simplifyauth.com.

iiq-rules-mcp is an independent product of SIMPLIFYAUTH CONSULTANCY SERVICES (OPC) PRIVATE LIMITED, not affiliated with, endorsed by, or sponsored by SailPoint Technologies. SailPoint, IdentityIQ, and related marks are trademarks of SailPoint Technologies, Inc., used only to describe compatibility.