InterSystems Developer for InterSystems

Posted on Aug 13 • Originally published at community.intersystems.com

iris-agentic-dev -- Give Your AI a Live Connection to IRIS, Part 1: The Problem, the Tool, and Getting Started

#sql #ai #coding #tooling

Part 1 of a series. Part 2 covers the full tool catalog. Part 3 covers ObjectScript skills. Part 4 covers benchmarking and measuring what actually improves.

The Problem Hiding in the Comments

Thomas Mazur's post "Frogs, Chickens, AI, and VS Code" on VS Code productivity — Peacock, scoped workspace files, Copilot Agent mode — drew a sharper problem in the comments. Pietro Di Leo and Mike.W pointed out that when you work server-side in VS Code, the isfs:// workspace most production IRIS shops use, Copilot can only see the files open in your editor. It cannot index the virtual filesystem. On a mature IRIS application with thousands of classes, the AI works through a keyhole.

John Murray pointed people at a project I've been building — iris-agentic-dev — and noted no Developer Community article existed for it yet. So here it is: why the problem exists, how the tool addresses it, and how to get it running in about five minutes.

Why the AI Can't See Your Namespace

When you open an isfs:// workspace, your IRIS classes live on the server, not on disk. The VS Code ObjectScript extension streams them to you on demand via the Atelier API — open a class, it fetches it; save it, it writes back. This works beautifully for editing.

AI assistants such as Copilot work differently. They need a picture of the code around the file you're editing. Who calls this method? What inherits from this class? What other code touches this global? On a local project, the assistant can scan the files to answer those questions. An isfs:// workspace materializes files only when you open them, so there is nothing complete to scan.

For a new project with a handful of classes, that may be tolerable. For a production IRIS system — ten thousand classes, Ensemble productions, custom %Library subclasses, business logic accumulated across years of development — the AI becomes nearly useless for the hard questions. It can help you write a new method if you paste in the surrounding context yourself. It cannot help you understand the system.

Give the AI a different kind of connection, one that can ask IRIS directly instead of crawling the disk.

What iris-agentic-dev Is

iris-agentic-dev is an MCP server — a background process that gives AI assistants a set of tools they can call to interact with a live IRIS instance. It works with GitHub Copilot (via the VS Code extension), Claude Code, Cursor, and OpenCode. The IRIS instance can run natively on Windows or Linux, or in Docker.

Once configured, the MCP server's tools are available directly from chat. VS Code 1.99 and later support MCP for Copilot Agent mode; Claude Code and OpenCode have supported it since launch.

iris-agentic-dev connects to IRIS through the same Atelier REST API used by the ObjectScript extension. The assistant can then:

Search the entire namespace — full-text, regex, by category, without opening anything
Compile classes and get errors back with line numbers
Run ObjectScript and see the output
Execute SQL queries against any namespace
Introspect class definitions — properties, methods, parameters, inheritance chains
Inspect Ensemble productions — which items are running, what's wired to what, message bodies, business rule logic, and drift between the running config and source control
Run unit tests and report results
Debug — map INT line numbers back to original source lines, pull error logs

Part 2 covers the complete tool catalog. Instead of guessing from a few open tabs, the assistant can ask IRIS about the namespace itself.

---

Built With the Community

I started the project after running into this limitation repeatedly in my own IRIS work. Community contributions have shaped it since — often from the same people who show up more than once. John Murray, who pointed people at this project in the Frogs and Chickens thread, also built the Server Manager authentication integration you'll use in Step 2 below: instead of typing credentials into a config file, the MCP server reads them straight from the OS keychain through the same AuthenticationProvider the Server Manager extension itself uses. Dorian TETU has contributed fixes across search accuracy, source control elicitation, and surgical-edit diffs.

The project is open source under the intersystems-community GitHub organization. Contributions and bug reports are welcome, including "It doesn't work on my setup."

Getting Started: VS Code + GitHub Copilot

If you already use VS Code with the InterSystems ObjectScript extension, this is the fastest path.

Prerequisites: VS Code, GitHub Copilot subscription, and the InterSystems ObjectScript extension (which you almost certainly already have).

Step 1 — Install the VS Code extension

Search for iris-agentic-dev in the VS Code Marketplace and install it. On first activation, the extension locates or downloads the MCP server binary: if you already have it on PATH (e.g. via brew install iris-agentic-dev), it uses that; otherwise it downloads the right binary for your platform automatically. Either way, it registers itself with Copilot — no manual wiring required.

The iris-agentic-dev tool set appears in Copilot's Agent mode after installation.

Step 2 — Verify the connection

Open Copilot Chat and switch to Agent mode. Ask:

"Call check_config and show me the result."

You should see your IRIS connection details — host, port, namespace, Atelier API version. If the InterSystems Server Manager extension is installed, iris-agentic-dev finds your server configuration and retrieves credentials from the OS keychain automatically. The VS Code extension follows the active objectscript.conn, so developers with several Server Manager entries keep using the connection selected for that workspace. When running the MCP server outside the VS Code extension, set IRIS_SERVER_NAME to the corresponding key from intersystems.servers if more than one server is configured. The check_config result shows which connection is active and which other servers were detected.

$Copilot displaying the result of the iris-agentic-dev check\_config tool$

check_config confirms the IRIS host, port, namespace, and connection source Copilot is using.

Step 3 — Ask something that requires the whole namespace

Now try a question that would be difficult to answer from open tabs alone:

"Search for all classes in this namespace that extend %Persistent. How many are there?"

"What are the properties and methods on MyApp.SomeClass?"

"Compile MyApp.*.cls and show me any errors."

None of these requires you to open the relevant files first. The assistant gets the answers from IRIS.

Getting Started: Claude Code

Install the binary (Mac):

brew tap intersystems-community/tap
brew install iris-agentic-dev

Or download directly from the releases page for Mac Intel, Linux, or Windows.

Configure the connection. Create ~/.iris-agentic-dev.toml:

host = "localhost"
web_port = 52773
username = "_SYSTEM"
password = "SYS"
namespace = "USER"

Register with Claude Code:

claude mcp add --scope user iris-agentic-dev -- iris-agentic-dev mcp

Then verify:

> Call check_config and show me the result.

Example: How iris-agentic-dev tools support analyzing an IRIS Interoperability application

Here is a real exchange against the irisdemo-demo-readmission production — a health interop demo that processes hospital discharge events and scores patients for readmission risk.

"How does an ADT A03 discharge message flow through this production?"

Step 1: find what's compiled.

iris_symbols("IRISDemo.*")
→ 31 classes: BO.*, BP.*, BS.*, DTL.*, Util.*, and more

Key classes: IRISDemo.BP.ReadmissionRisk.Process, IRISDemo.DTL.HL7Discharge, IRISDemo.DTL.HL7Update, IRISDemo.HISHL7v2FileFeedRoutingRule.

Step 2: find the router's rule.

extract_message_map_routing("IRISDemo.HISHL7v2FileFeedRoutingRule")
→ NOT_FOUND — Ens.Rule.Definition, not a routing table class

Ens.Rule.Definition classes hold routing logic in XData. The tool can't map that structure, so read the class source directly:

iris_doc("IRISDemo.HISHL7v2FileFeedRoutingRule.cls") → XData rules:
  Rule 1: docName=ADT_A01 or ADT_A08  → transform DTL.HL7Update, target Readmission Risk Process
  Rule 2: docName=ADT_A03             → transform DTL.HL7Update, target Readmission Risk Process

A03 discharges go through IRISDemo.DTL.HL7Update, which stamps UpdateMessageType="A03" on the request — that field is what lets the business process branch differently for discharges vs. admits.

Step 3: map the business process.

extract_message_map_routing("IRISDemo.BP.ReadmissionRisk.Process")
→ kind: bpl, 4 outbound calls:
    Update Encounter          → LACE SOAP Operation
    Calculate Risk with LACE  → LACE SOAP Operation
    Calculate Risk with ML    → Readmission ML Model Consumer
    EMR Readmission Update    → HisDB Encounter Update Operation

Step 4: get the full step tree.

docs_introspect("IRISDemo.BP.ReadmissionRisk.Process") → xdata_flow:
  Call:  Update Encounter          → LACE SOAP Operation
  Call:  Calculate Risk with LACE  → LACE SOAP Operation
  Call:  Calculate Risk with ML    → Readmission ML Model Consumer
  Call:  EMR Readmission Update    → HisDB Encounter Update Operation  [async]
  If:    Discharge OK?
           (request.UpdateMessageType = "A03") && (context.UpdateEncounterResult = 1)
    If:  Risk Alert?
           (context.RiskScore > 11) || (context.MLReadmissionRisk > 0.15)
      assign: Compose Alert Message
      Call:  Add Patient to Risk Program  → Care Team  [async]
      Call:  Alert Care Team              → Risk Alert Email Operation
      sync:  Follow up SLA 2 days
      If:    No follow up?  (synctimedout)

The session also flagged that IRISDemo.DTL.HL7Discharge exists and maps 9 HL7 fields to a DischargeRequest — but the routing rule never sends A03 through it. Dead code, spotted without opening a file.

The full exchange — every tool call, response, and reasoning step — is in this GitHub Gist.

In four steps the assistant answered the question: A03 discharges hit the router, get transformed into an UpdateEncounterRequest with the trigger event stamped as the branch signal, and the business process runs LACE and ML risk scoring in sequence — alerting the care team and starting a 2-day follow-up if either score exceeds the threshold. No files were open. Everything came from IRIS.

What's in the Next Parts

Part 2 — The Tools: A practical walkthrough of the tool catalog: what each tool does, when to use it, and which IRIS-specific problems it solves. The search, introspection, and Ensemble tools are especially useful for questions that open editor buffers cannot answer.

Part 3 — Skills: A live connection does not fix an AI model's weak grasp of ObjectScript: subtle syntax differences, %Status propagation, $$$ macros, and COS-specific idioms that are scarce in general training data. Skills are short instruction files that target these weaknesses. On my 22-task ObjectScript repair suite, a 205-word checklist called objectscript-review took the pass rate from 73% to 100% against Claude Sonnet 4.6 — a single run on a small public suite, with all the caveats that implies. Part 3 covers what the skills do; Part 4 covers how much to trust the number.

Part 4 — Benchmarking: How the benchmark harness works, how to run it, and what the numbers mean. That includes where skills help, where they have no effect, and at least one that appears to hurt performance when loaded globally — more instructions are not always better. It also covers the limits of a suite this size: contamination risk from public tasks, single-run variance, and why a lift measured on one model says little about another.

DEV Community