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 |
Annotated session: tracing an ADT^A03 through a production

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

1. Install
   iris-agentic-dev for IRIS
   from the VS Code Marketplace
2. 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"]

Quick start: Cursor IDE / Cursor CLI

Cursor is configured like other stdio MCP clients (~/.cursor/mcp.json), not like the
VS Code Copilot extension auto-registration path. Server Manager keychain and the Marketplace
extension behave differently (or not at all) in many Cursor setups.

See https://github.com/intersystems-community/iris-agentic-dev/blob/master/docs/cursor-quickstart.md for install, mcp.json, fleet
server= routing, and an explicit Cursor vs VS Code + Copilot comparison.

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

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:

1. Open IIS Manager → expand your server → Sites → Default Web Site
2. Right-click → Add Application. Set alias: api, physical path:
   C:\InterSystems\IRIS\CSP\bin (adjust to your install path)
3. Add a wildcard script handler mapping: executable = CSPms.dll, no verb restriction
4. 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:

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

Environment variables

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):

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

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

Search and introspection

Debugging

Generation

Interoperability

Administration

Learning agent, skills, and knowledge base

→ Full tool reference with error codes

Troubleshooting

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                # 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         # Run the skill benchmark harness
iris-agentic-dev --version                       # Print version

Documentation

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