{"slug": "iris-agentic-dev-give-your-ai-a-live-connection-to-iris-part-1-the-problem-the", "title": "iris-agentic-dev -- Give Your AI a Live Connection to IRIS, Part 1: The Problem, the Tool, and Getting Started", "summary": "InterSystems has released iris-agentic-dev, an open-source MCP server that gives AI coding assistants a live connection to IRIS data platform instances. The tool, built by Thomas Mazur with community contributions, addresses the limitation where AI assistants like GitHub Copilot cannot scan server-side IRIS workspaces, making them nearly useless for understanding large production systems. It works with GitHub Copilot, Claude Code, Cursor, and OpenCode, and connects via the Atelier REST API.", "body_md": "*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.*\n\nThomas Mazur's post [ \"Frogs, Chickens, AI, and VS Code\" ](https://community.intersystems.com/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\n\n`isfs://`\n\nworkspace most production IRIS shops use, Copilot can only see the files John Murray pointed people at a project I've been building — [iris-agentic-dev](https://github.com/intersystems-community/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.\n\nWhen you open an `isfs://`\n\nworkspace, 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.\n\nAI 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://`\n\nworkspace materializes files only when you open them, so there is nothing complete to scan.\n\nFor a new project with a handful of classes, that may be tolerable. For a production IRIS system — ten thousand classes, Ensemble productions, custom `%Library`\n\nsubclasses, 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.\n\nGive the AI a different kind of connection, one that can ask IRIS directly instead of crawling the disk.\n\n`iris-agentic-dev`\n\nis 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.\n\nOnce 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.\n\n`iris-agentic-dev`\n\nconnects to IRIS through the same Atelier REST API used by the ObjectScript extension. The assistant can then:\n\nPart 2 covers the complete tool catalog. Instead of guessing from a few open tabs, the assistant can ask IRIS about the namespace itself.\n\n---\n\nI 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`\n\nthe Server Manager extension itself uses. Dorian TETU has contributed fixes across search accuracy, source control elicitation, and surgical-edit diffs.\n\nThe project is open source under the `intersystems-community`\n\nGitHub organization. Contributions and bug reports are welcome, including \"It doesn't work on my setup.\"\n\nIf you already use VS Code with the InterSystems ObjectScript extension, this is the fastest path.\n\n**Prerequisites**: VS Code, GitHub Copilot subscription, and the [InterSystems ObjectScript extension](https://marketplace.visualstudio.com/items?itemName=intersystems-community.vscode-objectscript) (which you almost certainly already have).\n\nSearch 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`\n\n), it uses that; otherwise it downloads the right binary for your platform automatically. Either way, it registers itself with Copilot — no manual wiring required.\n\n*The iris-agentic-dev tool set appears in Copilot's Agent mode after installation.*\n\nOpen Copilot Chat and switch to **Agent mode**. Ask:\n\n\"Call check_config and show me the result.\"\n\nYou should see your IRIS connection details — host, port, namespace, Atelier API version. If the [InterSystems Server Manager](https://marketplace.visualstudio.com/items?itemName=intersystems-community.servermanager) extension is installed, `iris-agentic-dev`\n\nfinds your server configuration and retrieves credentials from the OS keychain automatically. The VS Code extension follows the active `objectscript.conn`\n\n, 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`\n\nto the corresponding key from `intersystems.servers`\n\nif more than one server is configured. The `check_config`\n\nresult shows which connection is active and which other servers were detected.\n\n`check_config`\n\n* confirms the IRIS host, port, namespace, and connection source Copilot is using.*\n\nNow try a question that would be difficult to answer from open tabs alone:\n\n\"Search for all classes in this namespace that extend`%Persistent`\n\n. How many are there?\"\n\n\"What are the properties and methods on`MyApp.SomeClass`\n\n?\"\n\n\"Compile`MyApp.*.cls`\n\nand show me any errors.\"\n\nNone of these requires you to open the relevant files first. The assistant gets the answers from IRIS.\n\n**Install the binary** (Mac):\n\n```\nbrew tap intersystems-community/tap\nbrew install iris-agentic-dev\n```\n\nOr download directly from the [releases page](https://github.com/intersystems-community/iris-agentic-dev/releases/latest) for Mac Intel, Linux, or Windows.\n\n**Configure the connection.** Create `~/.iris-agentic-dev.toml`\n\n:\n\n```\nhost = \"localhost\"\nweb_port = 52773\nusername = \"_SYSTEM\"\npassword = \"SYS\"\nnamespace = \"USER\"\n```\n\n**Register with Claude Code:**\n\n```\nclaude mcp add --scope user iris-agentic-dev -- iris-agentic-dev mcp\n```\n\nThen verify:\n\n```\n> Call check_config and show me the result.\n```\n\nHere is a real exchange against the [irisdemo-demo-readmission](https://github.com/intersystems/irisdemo-demo-readmission) production — a health interop demo that processes hospital discharge events and scores patients for readmission risk.\n\n\"How does an ADT A03 discharge message flow through this production?\"\n\n**Step 1: find what's compiled.**\n\n```\niris_symbols(\"IRISDemo.*\")\n→ 31 classes: BO.*, BP.*, BS.*, DTL.*, Util.*, and more\n```\n\nKey classes: `IRISDemo.BP.ReadmissionRisk.Process`\n\n, `IRISDemo.DTL.HL7Discharge`\n\n, `IRISDemo.DTL.HL7Update`\n\n, `IRISDemo.HISHL7v2FileFeedRoutingRule`\n\n.\n\n**Step 2: find the router's rule.**\n\n```\nextract_message_map_routing(\"IRISDemo.HISHL7v2FileFeedRoutingRule\")\n→ NOT_FOUND — Ens.Rule.Definition, not a routing table class\n```\n\n`Ens.Rule.Definition`\n\nclasses hold routing logic in XData. The tool can't map that structure, so read the class source directly:\n\n```\niris_doc(\"IRISDemo.HISHL7v2FileFeedRoutingRule.cls\") → XData rules:\n  Rule 1: docName=ADT_A01 or ADT_A08  → transform DTL.HL7Update, target Readmission Risk Process\n  Rule 2: docName=ADT_A03             → transform DTL.HL7Update, target Readmission Risk Process\n```\n\nA03 discharges go through `IRISDemo.DTL.HL7Update`\n\n, which stamps `UpdateMessageType=\"A03\"`\n\non the request — that field is what lets the business process branch differently for discharges vs. admits.\n\n**Step 3: map the business process.**\n\n```\nextract_message_map_routing(\"IRISDemo.BP.ReadmissionRisk.Process\")\n→ kind: bpl, 4 outbound calls:\n    Update Encounter          → LACE SOAP Operation\n    Calculate Risk with LACE  → LACE SOAP Operation\n    Calculate Risk with ML    → Readmission ML Model Consumer\n    EMR Readmission Update    → HisDB Encounter Update Operation\n```\n\n**Step 4: get the full step tree.**\n\n```\ndocs_introspect(\"IRISDemo.BP.ReadmissionRisk.Process\") → xdata_flow:\n  Call:  Update Encounter          → LACE SOAP Operation\n  Call:  Calculate Risk with LACE  → LACE SOAP Operation\n  Call:  Calculate Risk with ML    → Readmission ML Model Consumer\n  Call:  EMR Readmission Update    → HisDB Encounter Update Operation  [async]\n  If:    Discharge OK?\n           (request.UpdateMessageType = \"A03\") && (context.UpdateEncounterResult = 1)\n    If:  Risk Alert?\n           (context.RiskScore > 11) || (context.MLReadmissionRisk > 0.15)\n      assign: Compose Alert Message\n      Call:  Add Patient to Risk Program  → Care Team  [async]\n      Call:  Alert Care Team              → Risk Alert Email Operation\n      sync:  Follow up SLA 2 days\n      If:    No follow up?  (synctimedout)\n```\n\nThe session also flagged that `IRISDemo.DTL.HL7Discharge`\n\nexists and maps 9 HL7 fields to a `DischargeRequest`\n\n— but the routing rule never sends A03 through it. Dead code, spotted without opening a file.\n\nThe full exchange — every tool call, response, and reasoning step — is in this [GitHub Gist](https://gist.github.com/isc-tdyar/58a19b90f604fa786eab555815283dde).\n\nIn four steps the assistant answered the question: A03 discharges hit the router, get transformed into an `UpdateEncounterRequest`\n\nwith 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.\n\n**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.\n\n**Part 3 — Skills**: A live connection does not fix an AI model's weak grasp of ObjectScript: subtle syntax differences, `%Status`\n\npropagation, `$$$`\n\nmacros, 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`\n\ntook 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.\n\n**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.\n\n*Thomas Dyar — Sr. Manager AI Platform & Ecosystem, InterSystems, *`iris-agentic-dev`\n\n* is open source under the intersystems-community GitHub organization.*", "url": "https://wpnews.pro/news/iris-agentic-dev-give-your-ai-a-live-connection-to-iris-part-1-the-problem-the", "canonical_source": "https://dev.to/intersystems/iris-agentic-dev-give-your-ai-a-live-connection-to-iris-part-1-the-problem-the-tool-and-1kc0", "published_at": "2026-08-13 09:35:07+00:00", "updated_at": "2026-08-13 09:46:13.484359+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "ai-agents"], "entities": ["InterSystems", "iris-agentic-dev", "Thomas Mazur", "GitHub Copilot", "Claude Code", "Cursor", "OpenCode", "Atelier REST API"], "alternates": {"html": "https://wpnews.pro/news/iris-agentic-dev-give-your-ai-a-live-connection-to-iris-part-1-the-problem-the", "markdown": "https://wpnews.pro/news/iris-agentic-dev-give-your-ai-a-live-connection-to-iris-part-1-the-problem-the.md", "text": "https://wpnews.pro/news/iris-agentic-dev-give-your-ai-a-live-connection-to-iris-part-1-the-problem-the.txt", "jsonld": "https://wpnews.pro/news/iris-agentic-dev-give-your-ai-a-live-connection-to-iris-part-1-the-problem-the.jsonld"}}