iris-dev

Connect GitHub Copilot, Claude Code, or any MCP-compatible AI assistant directly to a live InterSystems IRIS instance. Your AI can compile, test, search, read, write, and debug ObjectScript without leaving the chat.

No Python. No pip. No npm. No API keys.

How it works

iris-dev runs as a local MCP (Model Context Protocol) server. Your AI assistant calls its tools — iris_compile, iris_doc, iris_execute, etc. — and iris-dev executes them against your real IRIS instance over the Atelier REST API. The AI sees compile errors, class definitions, and execution output in-line, the same way it would with a local filesystem.

Quick start — pick your setup

Option A: IRIS in Docker (local dev)

# 1. Install iris-dev (Mac Apple Silicon)
curl -fsSL https://github.com/intersystems-community/iris-dev/releases/latest/download/iris-dev-macos-arm64 \
  -o /usr/local/bin/iris-dev && chmod +x /usr/local/bin/iris-dev
xattr -d com.apple.quarantine /usr/local/bin/iris-dev 2>/dev/null

# 2. Let iris-dev find your container automatically
iris-dev init              # writes .iris-dev.toml from your running containers

# 3. Add to Claude Code (~/.claude/settings.json)

{
  "mcpServers": {
    "iris-dev": {
      "command": "iris-dev",
      "args": ["mcp"],
      "env": { "OBJECTSCRIPT_WORKSPACE": "${workspaceFolder}" }
    }
  }
}

Option B: Remote or server IRIS (no Docker)

# Set connection via env vars — no .iris-dev.toml needed

{
  "mcpServers": {
    "iris-dev": {
      "command": "iris-dev",
      "args": ["mcp"],
      "env": {
        "IRIS_HOST": "iris.example.com",
        "IRIS_WEB_PORT": "52773",
        "IRIS_USERNAME": "_SYSTEM",
        "IRIS_PASSWORD": "SYS",
        "IRIS_NAMESPACE": "MYAPP"
      }
    }
  }
}

For HTTPS or a non-root web gateway path:

"IRIS_SCHEME": "https",
"IRIS_WEB_PORT": "443",
"IRIS_WEB_PREFIX": "irisaicore"

Option C: VS Code Copilot Agent Mode

1. Install the binary (see Installation below)
2. Download vscode-iris-dev-*.vsix from the releases page
3. In VS Code: Extensions (Ctrl+Shift+X) → ... → Install from VSIX
4. Reload VS Code — iris-dev (IRIS) appears automatically in Copilot Chat → Agent mode → tools

The extension reads your existing objectscript.conn and intersystems.servers config — no extra setup if you already use the InterSystems VS Code extensions.

Installation

Mac

# Apple Silicon (M1/M2/M3):
sudo mkdir -p /usr/local/bin
curl -fsSL https://github.com/intersystems-community/iris-dev/releases/latest/download/iris-dev-macos-arm64 \
  -o /usr/local/bin/iris-dev && chmod +x /usr/local/bin/iris-dev
xattr -d com.apple.quarantine /usr/local/bin/iris-dev 2>/dev/null

# Intel Mac: replace "arm64" with "x86_64" above

Linux

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

Windows

1. Download iris-dev-windows-x86_64.exe from the releases page
2. Save it somewhere permanent, e.g. C:\Users\yourname\bin\iris-dev.exe
3. In VS Code User Settings (JSON), set the binary path:

"iris-dev.serverPath": "C:\\Users\\yourname\\bin\\iris-dev.exe"

WSL2: Use the Windows binary. Set IRIS_HOST to the Windows host IP — localhost in WSL2 resolves to the Linux VM, not the Windows host.

Tools

iris-dev exposes 23 tools to your AI assistant:

Tools marked ✓ Needs Docker require IRIS_CONTAINER to be set. Tools without the mark work over Atelier REST and work with any IRIS instance — local or remote.

Configuration reference

Environment variables

.iris-dev.toml (per-project config)

Drop this file in your project root and commit it so teammates get the same setup automatically.

# Local Docker container
container = "myapp-iris"
namespace = "MYAPP"

# Remote IRIS (alternative to Docker)
# host = "iris.example.com"
# web_port = 52773
# scheme = "https"          # for TLS
# web_prefix = "irisaicore" # for non-root gateway path

Generate from your running containers: iris-dev init

Enterprise containers (intersystems/iris, intersystems/irishealth)

Enterprise images ship with WebServer=0 — no private web server. The standard solution is the ISC Web Gateway container alongside IRIS. iris-dev auto-detects it.

# docker-compose snippet
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"]            # iris-dev scans port 52773
    entrypoint: ["/bin/sh", "/init.sh"]
    volumes: ["./webgateway-init.sh:/init.sh:ro"]

Three non-obvious setup gotchas in fresh containers — see iris-vscode-objectscript skill for the complete working webgateway-init.sh.

Connection discovery order

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

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

VS Code: Server Manager integration

If you use the InterSystems VS Code extensions, iris-dev reads your server definitions automatically. Your objectscript.conn should reference a named server so the full definition (including pathPrefix for non-standard gateways) is picked up:

"objectscript.conn": { "active": true, "server": "your-server-name" }

If iris-dev can't find your server: View > Output > iris-dev shows which servers were found and where.

Secure credential storage: If the InterSystems Server Manager extension is installed, iris-dev uses it to retrieve credentials from the OS keychain. On first use you'll be prompted for username and password. When the password prompt appears, click the 🔑 key icon before pressing Enter to store it in the keychain — subsequent VS Code restarts will then be fully silent. Pressing Enter without clicking 🔑 uses the password for the current session only. Server Manager is optional; without it iris-dev falls back to credentials in your server definition or MCP env vars.

Commands

iris-dev mcp           # Start the MCP server (used by Claude Code / Copilot)
iris-dev compile MyApp.Foo.cls   # Compile from the terminal
iris-dev init          # Generate .iris-dev.toml from running containers
iris-dev --version     # Check version

Contributing

Issues and PRs welcome. File bugs at the Issues tab — visible to the team and helps prioritization.

Questions or urgent issues: thomas.dyar@intersystems.com