| name | iris-agentic-dev |
| description | Configure, connect, and troubleshoot the iris-agentic-dev MCP server (iris_execute/iris_query/iris_doc/docs_introspect/kb/etc.) against an IRIS container or instance. Use when its tools return IRIS_UNREACHABLE, when pointing it at a new IRIS, or when a connection edit "isn't taking effect." Covers the .iris-agentic-dev.toml config, live file-watch reload, the OrbStack port-discovery gotcha, and the docker-exec fallback. |
| author | tdyar |
| managed_by | iris-agentic-dev |
iris-agentic-dev MCP
iris-agentic-dev is a Rust binary that runs an MCP server (iris-agentic-dev mcp)
exposing IRIS dev tools — iris_execute, iris_query, iris_doc, docs_introspect,
iris_compile, kb, iris_global, etc. Registered per-project in ~/.claude.json
under mcpServers, each with an env: { IRIS_CONTAINER: "<name>" }. It talks to IRIS
over the Atelier REST API (needs the web server / web gateway — port 52773-family).
The two facts that trip people up
-
Connection config lives in .iris-agentic-dev.toml, NOT the MCP env block.
Editing env in ~/.claude.json on a running server does nothing — env is injected
once at spawn. The .toml is the right lever.
-
The server re-reads .iris-agentic-dev.toml on every tool call (mtime check via
ConfigWatcher). A config edit takes effect the next time any MCP tool is called —
no restart, no reconnect needed. Do not tell the user "restart to apply."
IRIS_UNREACHABLE — cause and fix
IRIS_UNREACHABLE: no IRIS connection. Set IRIS_HOST and IRIS_WEB_PORT env vars,
or ensure IRIS is reachable on a discoverable port (52773, 41773, 51773, 8080).
Common cause with OrbStack/Docker: container = "<name>" triggers port-discovery
against a fixed probe list (52773 / 41773 / 51773 / 8080). OrbStack maps the
container's 52773 to a different, dynamic host port (e.g. 42773) — not on the list
→ IRIS_UNREACHABLE, even though the container is healthy.
Fix — add host + web_port to the project .iris-agentic-dev.toml:
container = "my-iris"
host = "localhost"
web_port = 42773
namespace = "USER"
username = "_SYSTEM"
password = "SYS"
Find the mapped port:
docker port <container-name> | grep 52773
⚠ OrbStack host ports are dynamic — if the container is recreated the port may
change. If the MCP breaks after a recreate, re-run docker port and update web_port.
A durable fix is pinning the port in compose/run config.
After editing .toml, call any MCP tool — it reconnects immediately.
.iris-agentic-dev.toml key reference
Generate a documented sample: iris-agentic-dev init
| Key | Notes |
|---|
container | Docker container name — enables auto port-discovery (probe list above) |
host | e.g. "localhost" — overrides discovery; use with web_port |
web_port | Atelier REST port (host-side). Community default 52773; Enterprise + web gateway varies |
web_prefix | URL path prefix (e.g. "iris" when Atelier is at /iris/api/atelier/) |
scheme | "http" (default) or "https" |
namespace | Default namespace for tool calls |
username / password | Prefer IRIS_USERNAME / IRIS_PASSWORD env vars over committing credentials |
Same names as CLI flags: --host (IRIS_HOST), --web-port (IRIS_WEB_PORT),
--namespace, --username, --password, --toolset (baseline/nostub/merged).
Atelier REST requirement
Works with:
- Community Edition images (PWS on 52773)
- Enterprise + ISC Web Gateway container (auto-detected)
Not supported: Enterprise standalone (intersystems/iris, no web gateway) — no
Atelier REST endpoint.
Fallback: docker exec when MCP is unavailable
cat > /tmp/script.txt <<'EOF'
zn "USER"
write
halt
EOF
docker exec -i <container> iris session IRIS < /tmp/script.txt
Parser gotchas (avoid when building scripts):
$listnext(...) inside a while condition confuses the terminal parser — use for loops insteadprintf-style %-escaping breaks multi-line scripts — use a heredoc file, not printf
Toolset flag
--toolset merged (default) exposes the full tool set including interop and container tools.
--toolset baseline — standard ObjectScript dev tools only.
--toolset nostub — excludes preview/stub tools.
