iris-agentic-dev

MCP server and CLI that connects AI coding agents to a live InterSystems IRIS instance. Compile ObjectScript, run SQL, search namespaces, run unit tests, inspect productions — from any MCP-compatible agent or from the command line.

Requires IRIS 2023.1 or later. Works with native IRIS on Windows or Linux, and with Docker.

Pick your mode

Mode 1 — MCP server

90+ tools exposed over the Model Context Protocol. Connect once; your agent calls tools by name. Works with Claude Code, GitHub Copilot, OpenCode, or any MCP client.

iris-agentic-dev mcp

To expose only the IRIS tools without the skill/KB/learning-agent surface, pass --no-skills (or set IRIS_NO_SKILLS=true). Useful when skills are installed separately and you want to avoid duplicate tool names in the MCP client:

iris-agentic-dev mcp --no-skills

→ Quick start: VS Code + Copilot | Quick start: Claude Code / OpenCode | Full connection docs

Mode 2 — CLI tool dispatch

One tool call, one subprocess, no server. Good for agents that run shell commands, CI scripts, and skill repos that need IRIS access without a persistent MCP process.

iris-agentic-dev tool iris_query '{"sql":"SELECT TOP 5 ID FROM Sample.Person"}'
iris-agentic-dev tool iris_compile '{"target":"MyApp.Foo.cls"}'
iris-agentic-dev tool iris_execute '{"code":"Write ##class(%SYS.ProcessQuery).GetInfo()"}'

→ Tool reference

Mode 3 — Skills only

No IRIS connection, no server. Installs ObjectScript instruction files into your agent's skill directory. The binary and skills are independent — installing one doesn't install the other.

iris-agentic-dev skill install

→ Skill docs | Full skill reference

Install

Mac (Homebrew)

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

brew upgrade iris-agentic-dev updates the binary only — installed skills are not touched by Homebrew. Run iris-agentic-dev skill install after upgrading to pick up new skills. Files installed before the managed_by marker was introduced (or installed by other means) will be skipped as unrecognized; pass --force to overwrite them and stamp them for automatic updates going forward.

Mac direct download (Apple Silicon)

curl -fsSL https://github.com/intersystems-community/iris-agentic-dev/releases/latest/download/iris-agentic-dev-macos-arm64 \
  -o /usr/local/bin/iris-agentic-dev && chmod +x /usr/local/bin/iris-agentic-dev
xattr -d com.apple.quarantine /usr/local/bin/iris-agentic-dev 2>/dev/null

Linux x86_64

curl -fsSL https://github.com/intersystems-community/iris-agentic-dev/releases/latest/download/iris-agentic-dev-linux-x86_64 \
  -o /usr/local/bin/iris-agentic-dev && chmod +x /usr/local/bin/iris-agentic-dev

Windows: Download iris-agentic-dev-windows-x86_64.exe from the releases page and place it on your PATH.

Quick start: VS Code + GitHub Copilot

The VS Code extension handles binary discovery and connection config automatically.

Prerequisites: VS Code, GitHub Copilot, InterSystems ObjectScript extension

Install iris-agentic-dev for IRIS from the VS Code Marketplace
Reload VS Code

iris-agentic-dev (IRIS) now appears in Copilot Chat → Agent mode → tools. It reads your existing objectscript.conn or intersystems.servers configuration — no additional setup needed.

To verify the connection, ask Copilot: "Call check_config and show me the result."

If the InterSystems Server Manager extension is installed, iris-agentic-dev reads your server list and retrieves credentials from the OS keychain automatically — no additional config needed. Set IRIS_SERVER_NAME if you have multiple servers configured.

Windows users: iris-agentic-dev works with native IRIS on Windows — Docker is not required. If you hit a 404 on /api/atelier, see Windows IIS setup below.

Quick start: Claude Code / OpenCode

After installing the binary, configure your agent:

Claude Code — add to ~/.claude.json:

{
  "mcpServers": {
    "iris-agentic-dev": {
      "command": "iris-agentic-dev",
      "args": ["mcp"],
      "env": {
        "IRIS_HOST": "localhost",
        "IRIS_WEB_PORT": "52773",
        "IRIS_USERNAME": "_SYSTEM",
        "IRIS_PASSWORD": "SYS",
        "IRIS_NAMESPACE": "USER"
      }
    }
  }
}

OpenCode — add to ~/.config/opencode/config.json:

{
  "mcp": {
    "iris-agentic-dev": {
      "type": "local",
      "command": ["/usr/local/bin/iris-agentic-dev", "mcp"],
      "enabled": true,
      "environment": {
        "IRIS_HOST": "localhost",
        "IRIS_WEB_PORT": "52773",
        "IRIS_USERNAME": "_SYSTEM",
        "IRIS_PASSWORD": "SYS",
        "IRIS_NAMESPACE": "USER"
      }
    }
  }
}

Note: OpenCode uses "type": "local" and "environment" (not "type": "stdio" and "env").

WSL2: The Windows OpenCode GUI cannot spawn Linux ELF binaries. Use the Windows .exe or invoke the Linux binary via wsl.exe:

"command": ["wsl.exe", "-e", "/usr/local/bin/iris-agentic-dev", "mcp"]

Connecting to IRIS

Native IRIS on Windows or Linux (no Docker)

Add a .iris-agentic-dev.toml file to your project root:

host = "localhost"
web_port = 80        # IIS default for IRIS 2024.1+; use 52773 for pre-2024.1
namespace = "USER"
username = "_SYSTEM"
password = "SYS"

Port reference

IRIS version	Web server	Default port
2024.1+ on Windows	IIS	80
2024.1+ on Linux	Apache	80
Pre-2024.1 (any OS)	PWS	52773

Windows IIS: `/api` web application required

This is the most common failure on Windows. IIS needs an explicit /api web application mapped to the IRIS Web Gateway module. Without it, /api/atelier returns 404 — even when the Management Portal loads correctly.

To fix:

Open IIS Manager → expand your server → Sites → Default Web Site
Right-click → Add Application. Set alias: api, physical path: C:\InterSystems\IRIS\CSP\bin (adjust to your install path)
Add a wildcard script handler mapping: executable = CSPms.dll, no verb restriction
Verify CSP.ini contains an [APP_PATH:/api] section

See the iris-windows-iis-setup skill for full step-by-step instructions with verification commands.

localhost vs 127.0.0.1: On some older Web Gateway builds, using localhost causes a brief connection error before each request. If you see connection delays, change to host = "127.0.0.1".

Docker (community image)

Run iris-agentic-dev init in your project directory — it detects any running IRIS containers and writes .iris-agentic-dev.toml automatically:

iris-agentic-dev init

Or configure manually:

container = "myapp-iris"
namespace = "MYAPP"

Docker (enterprise image)

Enterprise IRIS images (intersystems/iris, intersystems/irishealth) ship without a built-in web server. Run the ISC Web Gateway container alongside IRIS:

services:
  iris:
    image: containers.intersystems.com/intersystems/iris:2026.1
    ports: ["4972:1972"]
  webgateway:
    image: containers.intersystems.com/intersystems/webgateway:2026.1
    ports: ["52773:80"]
    entrypoint: ["/bin/sh", "/init.sh"]
    volumes: ["./webgateway-init.sh:/init.sh:ro"]

See the iris-vscode-objectscript skill for a working webgateway-init.sh.

VS Code Server Manager (zero-config)

If the InterSystems Server Manager extension is installed, iris-agentic-dev reads your server list from VS Code's settings.json and resolves credentials from the OS keychain — no .iris-agentic-dev.toml needed.

Single server configured: auto-connects, no extra setup.

Multiple servers configured: set IRIS_SERVER_NAME to the map key from intersystems.servers:

export IRIS_SERVER_NAME=dev-local

Use check_config to see which servers were detected and whether credentials resolved.

Per-connection policy (fleet / operate mode)

Add [policy.<server-name>] blocks to .iris-agentic-dev.toml to restrict which tool categories are permitted on a given server:

[policy.prod]
allow = ["query", "search", "docs"]

Blocked calls return error_code: "POLICY_GATE" with the list of allowed categories. Available categories: compile, execute, query, search, docs, source_control, debug, admin, skill, kb.

Connection discovery order

iris-agentic-dev resolves the IRIS connection in this order — first match wins:

CLI flags (--host, --web-port, --scheme)
.iris-agentic-dev.toml in the workspace root
Environment variables (IRIS_HOST, etc.)
VS Code settings.json (objectscript.conn / intersystems.servers)
VS Code Server Manager keychain (intersystems.servers + OS keychain credential)
Running Docker containers (scored by workspace name similarity)
Localhost port scan (52773, 41773, 51773, 8080)

Environment variables

Variable	Default	Description
`IRIS_HOST`	`localhost`	IRIS web gateway hostname
`IRIS_WEB_PORT`	`52773`	Web gateway port
`IRIS_SCHEME`	`http`	`http` or `https`
`IRIS_WEB_PREFIX`	(empty)	URL path prefix for non-root gateway installs
`IRIS_USERNAME`	`_SYSTEM`	IRIS username
`IRIS_PASSWORD`	`SYS`	IRIS password
`IRIS_SERVICE_USERNAME`	(empty)	Least-privilege account for execute/query/write tools
`IRIS_SERVICE_PASSWORD`	(empty)	Password for `IRIS_SERVICE_USERNAME`
`IRIS_NAMESPACE`	`USER`	Default namespace
`IRIS_CONTAINER`	(empty)	Docker container name (required for ✦ tools)
`IRIS_SERVER_NAME`	(empty)	Server Manager server name (multiple servers)
`OBJECTSCRIPT_WORKSPACE`	`$PWD`	Workspace root for `.iris-agentic-dev.toml` lookup
`IRIS_ENABLED_TOOLS`	(empty)	Comma-separated allowlist — expose only these tools

Privilege separation for arbitrary execution

iris_execute, iris_execute_method, iris_query (mode="write"), and iris_global (set/kill) can run arbitrary ObjectScript/SQL. Under a %All account these can edit class and routine code — even by indirection — bypassing the SCM lock.

Set IRIS_SERVICE_USERNAME / IRIS_SERVICE_PASSWORD to a least-privilege IRIS account (no %Development resource, code database mounted read-only). Those four tools then authenticate as that account, so code edits fail with <PROTECT> at the IRIS privilege layer. Code-writing tools (iris_doc put, iris_source_control, iris_compile) keep using the primary IRIS_USERNAME so audit stays attributed to the real user.

Skills — improve AI output for ObjectScript

Skills are concise instruction files that teach your AI assistant ObjectScript-specific patterns and common mistakes. They work with or without the MCP server and require no IRIS connection.

Skills and the MCP server are independent — installing the binary installs no skills.

Tested with Claude Sonnet 4.6 on the ObjectScript repair suite (22 tasks):

Benchmark suite	Baseline	With top skill	Lift
ObjectScript repair (22 tasks)	73%	100%	+27%

The top skill is objectscript-review — a 205-word checklist that catches the 10 most common ObjectScript mistakes before the AI writes any code.

Read the +27% as a rough signal — one run, one model, 22 tasks that may be in training data. BENCHMARKING.md covers the caveats and lets you run it yourself.

Install skills:

iris-agentic-dev skill install                                # full pack, Claude Code + OpenCode
iris-agentic-dev skill install objectscript-review           # selective
iris-agentic-dev skill install --agent copilot               # repo-scoped Copilot instructions
iris-agentic-dev skill list                                  # check install status

VS Code Copilot: The extension installs the binary only. Run iris-agentic-dev skill install --agent copilot from a git repo root to install skills into .github/instructions/.

→ Full skill docs

Skill inventory

Skill	What it does	Benchmark
`objectscript-review`	Hard-gate checklist: 10 most common AI mistakes in ObjectScript	100% repair
`objectscript-guardrails`	All-in-one hard gate, works without MCP	86% repair
`objectscript-sql-patterns`	IRIS SQL quirks: reserved words, SQLCODE, table naming, NULL handling	100% SQL
`objectscript-unit-test`	Generates `%UnitTest` scaffolding from live class introspection	86% repair
`objectscript-list-patterns`	`%List`, `$LISTBUILD`, `$LISTNEXT`, `$LISTTOSTRING` patterns	91% repair
`objectscript-navigation`	Codebase discovery using MCP introspection tools	82% repair
`objectscript-tdd`	Compile-test-fix loop for iterative development
`objectscript-debugging`	Maps `.INT` offsets to `.CLS` source lines, reads error logs
`objectscript-repair`	Coordinated fixes across multiple dependent classes
`iris-docs`	Fetches live IRIS class reference before implementing any API — eliminates hallucinated methods
`iris-vector-ai`	IRIS vector search syntax (HNSW, `VECTOR_COSINE`, `TO_VECTOR`)	domain
`iris-connectivity`	IRIS connection APIs from Python, Java, JDBC, ODBC	domain
`ensemble-production`	Interoperability production lifecycle, logs, queues	domain
`iris-devtester`	`IRISContainer` factory methods and test fixture patterns	domain

Note: some skills hurt if loaded globally. objectscript-loop-patterns measured −19% lift when loaded for all tasks. Domain skills should only load when working in those areas. See BENCHMARKING.md.

See skills/ for the full list and how to contribute a skill.

Tools

Most tools work over the Atelier REST API and connect to any IRIS instance — no Docker required unless noted. Tools marked ✦ require IRIS_CONTAINER. Tools marked 🔒 are write-gated (suppressed on Live instances unless IRIS_ALLOW_PROD=1).

Tools that can reach patient data or IRIS internals are blocked before they run unless you opt in. See Data safety gates for what is blocked and how to permit it.

Code

Tool	What it does
`iris_compile`	Compile a class, routine, or wildcard. Returns errors with line numbers.
`iris_doc`	Read, write, delete, or check any IRIS document.
`iris_execute`	Run ObjectScript, return output.
`iris_execute_method`	Invoke a `ClassMethod` directly by class+method+args, no boilerplate.
`iris_query`	Execute SQL, return rows as JSON. `mode=explain\|count\|write` for plans, counts, and gated DML.
`iris_test`	Run `%UnitTest` tests, return structured pass/fail results.
`iris_global`	Read, write, kill, or list IRIS global nodes. Patient-data and system globals are gated.
`iris_coverage`	Measure ObjectScript line coverage via `%Monitor.System.LineByLine`.
`iris_source_control` ✦	Check lock status, checkout, execute SCM actions.

Search and introspection

Tool	What it does
`iris_symbols`	Search classes and methods via `%Dictionary`.
`iris_symbols_local`	Search `.cls`/`.mac`/`.inc` files on disk by glob — no IRIS connection required.
`docs_introspect`	Deep class inspection: methods, properties, XData, superclasses.
`iris_search`	Full-text search across the namespace. Supports regex and category filters.
`iris_info`	Namespace discovery: documents, jobs, CSP apps, metadata.
`iris_macro`	Macro inspection: list, signature, definition, expand.
`iris_table_info`	Inspect a SQL table: class-projected vs. DDL, backing storage globals.
`resolve_dynamic_dispatch`	Resolve `$classmethod`/`##class({var})` polymorphic dispatch to candidate classes.
`extract_message_map_routing`	Extract a compiled Ensemble `MessageMap` routing table.
`find_subclass_implementations`	Find all concrete subclass implementations of a method.

Debugging

Tool	What it does
`iris_debug`	Map INT offsets to source lines, fetch error logs, capture error state.
`iris_get_log`	Retrieve a full result by `log_id` when a tool returns `truncated: true`.
`check_config`	Show active connection state — host, container, config file, write tool status.

Generation

Tool	What it does
`iris_generate`	Build a context-rich prompt for generating ObjectScript. No API key required.
`iris_generate_class`	Generate and compile a class from a description (requires LLM API key).
`iris_generate_test`	Generate `%UnitTest` scaffolding for an existing class.

Interoperability

Tool	What it does
`iris_production` ✦	Start, stop, update, check, or recover a production.
`iris_interop_query` ✦	Query production logs, queue depths, or message archive.
`iris_production_item` 🔒	Enable, disable, or get/set settings on a production config item.
`iris_production_diff`	Diff the running production config against the last source-controlled version.
`iris_message_body`	Read a message body by ID. Blocked unless the connection permits patient data.
`iris_business_rule_info`	List or inspect Ensemble business rules.
`iris_credential_list`	List Ensemble credentials (IDs/usernames only — passwords never returned).
`iris_credential_manage` 🔒	Create, update, or delete an Ensemble credential.
`iris_lookup_manage`	Read, write, delete, or list Ensemble lookup table entries (write actions gated).
`iris_lookup_transfer`	Export or import an Ensemble lookup table as XML (import gated).

Administration

Tool	What it does
`iris_admin`	List namespaces, databases, users, roles, web apps; create/delete users; real-time observability.
`journal_search`	Search the IRIS journal for SetKill records by global pattern and/or time range.
`iris_namespace_list`	List all namespaces on the connected instance.
`iris_namespace_create` 🔒	Create a new namespace.
`iris_database_list`	List databases and their paths.
`iris_database_stats`	Disk usage and block-level stats for a database.
`query_audit_log`	Query the IRIS SQL audit log for recent activity.
`my_access`	Show the current user's roles and resource permissions.
`capability_matrix`	Show which tools are enabled/disabled and why (gates, policy, container availability).
`iris_containers` ✦	List, select, or start IRIS Docker containers.

Learning agent, skills, and knowledge base

Tool	What it does
`agent_history`	Recent tool-call history for the current session.
`agent_stats`	Learning agent status: skill count, pattern count, KB size.
`telemetry_query`	Query the durable telemetry record beyond the in-memory session.
`skill`	Manage the learning agent skill registry: list, describe, search, forget, or propose.
`skill_community`	Browse or install community skills published to subscribed GitHub repos.
`kb`	Index markdown/text into the IRIS knowledge base, or recall content by keyword.

→ Full tool reference with error codes

Troubleshooting

Symptom	Likely cause	Fix
404 on `/api/atelier` (Windows)	IIS missing `/api` web application	See Windows IIS setup
`check_config` works but compile/search fail	Atelier `Recurse=0`	Management Portal → Security → Web Apps → `/api/atelier` → enable Recurse
All tools fail, namespace listing works	API version mismatch	Verify IRIS supports Atelier v8
403 on write operations	Insufficient permissions	Use a user with `%DB_USER` or `%All` role
Connection delays on Windows	`localhost` DNS issue	Use `host = "127.0.0.1"` in `.iris-agentic-dev.toml`
`SERVER_MANAGER_CREDENTIAL_ERROR`	Credential not in OS keychain	VS Code → Server Manager → right-click server → Reconnect
`SERVER_MANAGER_AMBIGUOUS`	Multiple SM servers, no server name	Set `IRIS_SERVER_NAME=<server-key>`

For verbose HTTP logging:

iris-agentic-dev mcp --verbose 2>debug.log

→ Full troubleshooting guide

Commands

iris-agentic-dev mcp                              # Start the MCP server
iris-agentic-dev tool <name> <json>              # Call a tool directly (no server)
iris-agentic-dev compile MyApp.Foo.cls           # Compile from the terminal
iris-agentic-dev skill install [names]           # Install skills
iris-agentic-dev skill list                      # Check skill install status
iris-agentic-dev init                            # Generate .iris-agentic-dev.toml
iris-agentic-dev benchmark --skill <path>        # Run the skill benchmark harness
iris-agentic-dev --version                       # Print version

Documentation

Guide	Contents
docs/connecting.md	Native IRIS, Docker, Server Manager, policy gates, env vars, discovery order
docs/tools.md	Full tool catalog with descriptions and error codes
docs/skills.md	Skill inventory, benchmark results, CLI install reference
docs/troubleshooting.md	Symptom table, CLI commands, verbose logging
docs/ecosystem-integration.md	Patterns for downstream projects and skill repos

Contributing

Issues and pull requests are welcome. File bugs at the Issues tab.

To contribute a skill: write a SKILL.md, run the benchmark, submit a PR with your results. See BENCHMARKING.md.

Questions: thomas.dyar@intersystems.com

Name		Name	Last commit message	Last commit date
.cargo		.cargo
.claude-plugin		.claude-plugin
.github/workflows		.github/workflows
.vscode		.vscode
Formula		Formula
benchmark		benchmark
contrib/aihub		contrib/aihub
crates		crates
docs		docs
outputs		outputs
scripts		scripts
skills		skills
specs		specs
tests		tests
vscode-iris-agentic-dev		vscode-iris-agentic-dev
.dockerignore		.dockerignore
.gitignore		.gitignore
.markdownlint-cli2.jsonc		.markdownlint-cli2.jsonc
.prettierignore		.prettierignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
coverage-floors.toml		coverage-floors.toml
iris-agentic-dev.toml		iris-agentic-dev.toml
requirements-test.txt		requirements-test.txt
rust-toolchain.toml		rust-toolchain.toml
skills.sh.json		skills.sh.json

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

iris-agentic-dev

Pick your mode

Mode 1 — MCP server

Mode 2 — CLI tool dispatch

Mode 3 — Skills only

Install

Mac (Homebrew)

Mac direct download (Apple Silicon)

Linux x86_64

Quick start: VS Code + GitHub Copilot

Quick start: Claude Code / OpenCode

Connecting to IRIS

Native IRIS on Windows or Linux (no Docker)

Port reference

Windows IIS: /api web application required

Docker (community image)

Docker (enterprise image)

VS Code Server Manager (zero-config)

Per-connection policy (fleet / operate mode)

Connection discovery order

Environment variables

Privilege separation for arbitrary execution

Skills — improve AI output for ObjectScript

Skill inventory

Tools

Code

Search and introspection

Debugging

Generation

Interoperability

Administration

Learning agent, skills, and knowledge base

Troubleshooting

Commands

Documentation

Contributing

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Windows IIS: `/api` web application required