How to use iiq-rules-mcp — from install to your first verified rule¶

This guide walks you from a downloaded wheel to a confirmed IdentityIQ rule authored by your AI assistant and proven against your own IIQ installation. Time budget: about 20 minutes, most of it gathering your IIQ artifacts.

What this product does, in one paragraph: it is an MCP server that grounds an AI assistant in your licensed IdentityIQ install — your identityiq.jar, your WEB-INF/lib, your sailpoint.dtd, your object export — and gates every drafted rule through seven verification stages before you ever run iiq console import. Every answer carries one of four verdicts: confirmed (positively verified against a named substrate), refuted (positively contradicted — fix it), unverifiable (could not be checked — never treat as clean), or advisory (a calibrated judgment aid). "We could not check" is never allowed to look like "clean."

1. Before you start¶

Brand-new machine? Follow the from-zero setup guide first — it installs uv, Python, the JDK, and Claude Desktop step by step on Windows and macOS, then hands back here.

You need four things:

#	Requirement	Notes
1	Python 3.11+ and `uv` (or pipx)	`uv` recommended — one-line tool installs
2	A JDK	17+ recommended, 11 minimum (enforced at boot). Any vendor.
3	Your licensed IIQ 8.1 artifacts	see the list below — nothing of SailPoint's ships with this product; you bring your own
4	An MCP client	Claude Desktop is the primary target; any stdio MCP client works

Gather your IIQ artifacts¶

From your IIQ deployment (an exploded identityiq webapp, a sandbox VM, or your build tree):

identityiq.jar — at WEB-INF/lib/identityiq.jar.
The whole WEB-INF/lib directory — the server needs the full runtime classpath, including bsh.jar (the BeanShell parser). If you have WEB-INF/lib-connectors, include that too. A identityiq.jar copied out alone is not enough — boot will refuse and tell you so.
sailpoint.dtd — generate it from the IIQ console (below) so it matches your exact release. Same-release matters: the server structurally verifies that your JAR, DTD, and export belong together and stamps pins_ok on every answer.
Optional but recommended: an object export — generate it from the IIQ console (below). This lets the gate resolve <Reference>s (rules, applications, …) against what actually exists in your deployment. Without it, reference checks answer unverifiable — honestly labeled, never silently skipped.

Generate the DTD and the export from the IIQ console¶

Both come from iiq console, run on your IIQ host (the iiq launcher lives in WEB-INF/bin; on Windows use iiq.bat). The console must be able to reach your IIQ database — run it where IIQ is deployed.

$ ./iiq console

> dtd /var/tmp/sailpoint.dtd
dtd written to "/var/tmp/sailpoint.dtd"

> export -clean /var/tmp/myobjects.xml
...

> quit

dtd <filename> writes the sailpoint.dtd for this build — the most reliable source (a DTD copied from another release is the classic cause of pins_ok: false). On Windows, use a Windows path, e.g. dtd C:\temp\sailpoint.dtd.
export -clean <filename> writes a portable object catalog with environment-specific IDs stripped. Optional but recommended.

Then copy the two generated files (plus the jars) to the machine where your MCP client runs.

Copy these to the machine where your MCP client runs, e.g.:

C:\iiq\WEB-INF\lib\            (all jars, incl. identityiq.jar and bsh.jar)
C:\iiq\sailpoint.dtd
C:\iiq\exports\myobjects.xml   (optional)

2. Install¶

Download the wheel from the Releases page, then:

uv tool install --from <path-to-downloaded-wheel> iiq-rules-mcp

This installs two commands: iiq-rules-mcp (the server your MCP client launches — you never run it by hand) and iiq-rules-activate (trial and license management).

Quick sanity check — both of these "failing" politely is correct at this point:

iiq-rules-mcp            → "ERROR: no IIQ JAR(s) configured" (config comes next)
iiq-rules-activate status → mode "unlicensed" (trial comes in step 5)

3. Configure your MCP client¶

For Claude Desktop: Settings → Developer → Edit Config opens claude_desktop_config.json. Add the server under mcpServers:

{
  "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\\myobjects.xml"
      }
    }
  }
}

Notes:

IIQ_LIB_DIRS takes multiple directories separated by ; on Windows and : on macOS/Linux.
Windows JSON needs doubled backslashes, as shown.
Omit IIQ_OBJECTS_EXPORT if you don't have an export yet — everything else still works, and the affected checks label themselves.
Any other stdio MCP client: same idea — command iiq-rules-mcp, plus these environment variables.

Then fully restart the client. For Claude Desktop that means Quit from the system-tray/menu-bar icon, not just closing the window — it keeps MCP servers alive across window closes.

4. First boot — check what you're grounded in¶

In a new chat, ask:

Run iiq_grounding_status and summarize it.

What a fully grounded session looks like:

grounding.iiq_version — your build string, e.g. 8.1 8cbeb0e-…
attestation.markers_ok: true — sailpoint.object.Identity, sailpoint.object.Rule, and bsh.Parser all loaded from your jars
pins_ok: true — your export, DTD, and JAR agree structurally (same release)
degradations: [] — nothing is silently off; if the DTD or export is missing, the affected capabilities are named here instead

This server refuses to boot rather than serve half-truths. If the tools never appear in your client, see Troubleshooting — the log always names the fix.

5. Start your free trial (or activate a license)¶

Evaluation is free and full-featured for 7 days — one trial per person per device, no card:

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

Bought a license? The email you received contains a key:

iiq-rules-activate key IIQR-XXXX-XXXX-XXXX

Useful any time:

iiq-rules-activate status       # current mode, expiry, licensee
iiq-rules-activate sync         # force a license/lease refresh now

How licensing behaves — no surprises by design:

State	Tools answer?	What you'll see
`trial` / `licensed`	yes	normal verdicts; a heads-up warning in the trial's last 3 days
`grace`	yes	you've been offline past a lease renewal — reconnect within 3 days
`trial_expired`, `expired`, `lease_required`, `unlicensed`, `invalid`	no	every tool answers with the reason and the exact command or link that fixes it — `iiq_grounding_status` always answers so you can always inspect the state

Individual licenses are one person, one device. Moving machines is self-serve (twice a year): on the old machine iiq-rules-activate deactivate --email you@…, then activate on the new one. Buying during a trial needs zero reconfiguration — the background license sync picks up the upgrade on its own (or run iiq-rules-activate sync to get it immediately).

The license state is stamped on every response, so you are never guessing.

6. Author your first rule — the workflow¶

The server ships an authoring contract (exposed to your client as the iiq_rule_authoring_contract prompt) that teaches the model this loop. You just describe what you need. A good first prompt:

Using the iiq-rules-mcp tools, write an IdentityIQ Correlation rule that matches incoming accounts to identities by employeeId. Ground every API you use, run the result through iiq_verify_rule_artifact, repair until it is confirmed, and show me the final verdict, any advisories, and anything unverifiable.

Behind the scenes the model should (and, with the bundled prompt, will):

Check grounding — iiq_grounding_status.
Pick the right rule type — iiq_rule_catalog (102 types, searchable by scenario; selection guidance is always advisory).
Ground the contract — iiq_rule_signature("Correlation") for the injected variables and expected return; iiq_class_lookup / iiq_method_signature for every API it plans to touch (invented API does not survive reflection against your jar).
Draft the rule XML — CDATA-wrapped <Source>, contract-true <Signature>, correct DOCTYPE.
Gate it — iiq_verify_rule_artifact runs seven stages and returns ONE verdict. Anything refuted names the stage, the line, and the fix; the model repairs and re-gates until confirmed.

Every tool named above — and the rest of the 21 — is documented with its arguments, verdict semantics, and an example ask in the tool reference.

Reading the gate's answer¶

The response is a JSON envelope. The parts that matter to you:

verdict: "confirmed"            ← the only acceptable end state
result.stages[…]                ← per-stage verdicts (xml_dtd, signature,
                                   references, bsh_parse, scope, members, reviews)
result.advisories[…]            ← non-blocking findings — read them
warnings / limits               ← anything bounded or worth knowing
grounding / license             ← what this answer was grounded in

House rules worth adopting as team policy:

Never import a rule the gate did not confirm.
Read every advisory — they are calibrated nudges (CDATA hygiene, best practices, security, performance), not noise.
Treat unverifiable as exactly that. A rule carrying <Reference>s with no export configured cannot be called verified — supply the export or verify those references yourself.

What `confirmed` means — and what it does not¶

confirmed means: the XML validates and is import-ready for your DTD, the type and <Signature> match the registry contract, every import and API call exists on your classpath (inherited members included), the BeanShell parses (parsed, never executed), and every variable read is accounted for. It is backed by calibration on real rules and live import sweeps.

It does not mean the logic does what your requirement means. Runtime semantics — business logic, data assumptions, connector behavior — are out of scope by design, and every gate response says so in its limits. Test in a sandbox like you would any human-written rule.

Prompt library — 15 ready-to-use requests¶

Copy any prompt into Claude Desktop, swapping application names and attributes for your environment. End every prompt with this standing instruction so the model grounds and gates instead of free-styling:

Ground every API you use with the iiq-rules-mcp tools, run the result through iiq_verify_rule_artifact, repair until it is confirmed, and show me the final verdict, all advisories, and anything unverifiable.

Pick the right type first (start here when unsure): "I need IIQ to recompute a user's department from their HR record on every identity refresh — which rule type fits? Use iiq_rule_catalog to shortlist candidates, recommend one, and show me its signature contract with iiq_rule_signature."
Correlation: "Write a Correlation rule for our Active Directory application that matches accounts to identities by employeeNumber, falling back to a case-insensitive email match when employeeNumber is empty."
BuildMap (file import): "Write a BuildMap rule for a delimited HR file: trim every value, convert HIRE_DT from DD-MM-YYYY into a Java Date, and derive a boolean active column that is true when STATUS is A or L."
IdentityCreation: "Write an IdentityCreation rule that sets displayName as 'lastname, firstname', copies employeeType from the authoritative HR account, and defaults the region attribute to 'EMEA' when the source value is empty."
IdentityAttribute: "Write an IdentityAttribute rule that computes a lifecycleState value: 'active' when HR status is A, 'leave' when L, 'inactive' otherwise."
ManagerCorrelation: "Write a ManagerCorrelation rule that resolves the manager by matching the HR feed's MANAGER_ID against identities' employeeNumber."
CertificationExclusion: "Write a CertificationExclusion rule that removes service accounts (names starting with 'svc-') and the 'Emergency-BreakGlass' entitlement from manager certifications, logging each exclusion with the reason."
Policy (SoD): "Write a Policy rule that flags a violation when one identity holds both the 'AP-Invoice-Create' and 'AP-Payment-Approve' roles, returning a PolicyViolation whose description names both roles."
BeforeProvisioning: "Write a BeforeProvisioning rule for AD that rewrites the OU in the distinguishedName by the identity's country attribute: IN → OU=India, DE → OU=Germany, anything else → OU=Global."
AfterProvisioning: "Write an AfterProvisioning rule that emails the 'Provisioning-Failure' template to the helpdesk — with the identity name and the error text — whenever the ProvisioningResult is failed or retry."
Field Value (LCM): "Write a Field Value rule that generates a unique sAMAccountName: first initial + last name, lowercase, appending 2, 3, 4… until no existing AD account link carries that value."
WebService before-operation: "Write a WebServiceBeforeOperation rule that fetches an OAuth bearer token from the token endpoint configured on the application and adds it as the Authorization header before the Get Accounts operation runs."
WebService after-operation: "Write a WebServiceAfterOperation rule for Get Accounts that maps the JSON users array into account maps and follows the response's nextLink until it is empty."
JDBC provisioning: "Write a JDBCOperationProvisioning rule for the Disable operation that calls the DEACTIVATE_USER stored procedure with the account's native identity and marks the ProvisioningResult committed on success."
Audit an existing rule: "Here is a rule from our repository: [paste the XML]. Run the full gate on it, explain every finding in plain language, and propose the minimal fix for anything refuted."

Two expectations to set with your team:

Connector-native types are labeled, not verified. The six Connector* types (e.g. ConnectorBeforeCreate for AD home directories) execute natively via IQService — the gate answers unverifiable for their BeanShell stages by design. That is honest labeling, not a failure.
confirmed is the floor, not the finish. It proves packaging, API existence, signature, scope, and references — business logic still gets a sandbox test, like any human-written rule.

7. Day-to-day tips¶

Start sessions with iiq_grounding_status (or let the model do it) — it is the cheapest way to catch a moved file or a swapped environment.
Point at the right environment. The gate proves rules against the artifacts you configured. Verifying against a dev export and importing to prod re-introduces exactly the drift this product exists to remove.
Refresh your export after significant object changes (export -clean again) — the server notices the file changed and re-reads it automatically, mid-session.
Rule references unresolved? The finding includes up to three "did-you-mean" object names from your own catalog. Set IIQ_DISABLE_CATALOG_SUGGESTIONS=true if your policy forbids even that.
Other 8.x releases: the mechanisms are identical, but calibration ran on 8.1 — boot attestation and pins_ok will tell you loudly if your substrates disagree. Treat non-8.1 as needing your own sandbox validation.

8. Troubleshooting¶

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

Symptom / log message	Cause	Fix
"no IIQ JAR(s) configured" (exit 2)	required env vars missing	set `IIQ_JAR_PATH` and `IIQ_LIB_DIRS` in the client config
"configuration invalid" naming a path (exit 2)	a set-but-wrong path — this is deliberate fail-fast, never a silent degrade	fix the typo
"JVM startup failed" (exit 3)	the default JVM on the machine is broken/wrong-arch	set `IIQ_JVM_PATH` to your JDK's `jvm.dll` (Windows) or `libjvm` (macOS/Linux)
"BOOT REFUSED … bsh.Parser … WEB-INF/lib" (exit 4)	classpath has the jar but not the libs	point `IIQ_LIB_DIRS` at the full `WEB-INF/lib` (it ships `bsh.jar`)
Java version refused	JDK below 11	install 17+
`pins_ok: false` on every answer	your JAR / DTD / export come from different releases	re-copy all three from the same install
DTD tools answer `unverifiable`	`IIQ_DTD_PATH` unset	set it (or accept the labeled degradation)
references answer `unverifiable`	no export configured	run `export -clean` and set `IIQ_OBJECTS_EXPORT` — only matters for rules that carry `<Reference>`s
license `invalid` — "bound to a different device"	the license file was copied from another machine	migrate properly: `deactivate` there, `key` here
license `lease_required`	too long offline	run `iiq-rules-activate sync` while online (it also retries on its own)
license `invalid` — "clock rollback detected"	system clock is behind what this machine has already seen	fix the system clock
tools vanished after an upgrade	the client kept an old server process alive	fully quit the client from the tray/menu bar, relaunch

9. Privacy and network — exactly¶

Rule verification makes zero network calls. Your rule content, file paths, and anything read from your IIQ installation never leave your machine. There is no telemetry. All of this is observable with any process/network monitor — and enforced by the product's own test suite.
The only network traffic in the product is license management: starting a trial, activating a key, and a roughly monthly lease renewal (30-day leases). Those requests carry your email (signup/deactivation only), the license id, salted one-way hashes of device identifiers, and — at trial start and activation only — the EULA version you accepted plus the local timestamp of that acceptance — never hostnames, never file paths, never rule content.
The optional export is read locally. The only customer-derived strings that can appear in a response are the ≤3 did-you-mean object names (see the strict-mode switch above).

10. Getting help¶

A divergence is gold. If the gate said confirmed and IIQ rejected the rule (or the reverse), file an issue with: the exact console/import error, the gate's verdict JSON, and your IIQ version. Measured divergences become shipped, regression-pinned checks — every check in the gate today was born this way.
Questions & licenses: contact@simplifyauth.com — commercial terms in COMMERCIAL.md, security policy in SECURITY.md.

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.