IRIS MCP Server Suite

Pre-Release — This project is under active development and has not yet been published to npm or IPM. Install by cloning the repository (see Quick Start below). Package registry publishing is planned for a future release. See https://github.com/jbrandtmse/iris-execute-mcp-v2/blob/main/CHANGELOG.md for the 2026-04-09 pre-release breaking change to tool names.

Give AI assistants structured, safe access to InterSystems IRIS.

The IRIS MCP Server Suite is a collection of five specialized Model Context Protocol (MCP) servers that let AI coding assistants — Claude, Copilot, Cursor, and others — work directly with InterSystems IRIS. Each server covers a distinct operational domain so you can install only what you need.

Servers

85 tools across 5 servers — install one or all.

Meta-package

Once published, all servers will be installable at once with npm install -g @iris-mcp/all. See the meta-package README for details.

Which Server Do I Need?

Prerequisites

• Node.js 18 or later
• InterSystems IRIS 2023.1 or later (including IRIS for Health, HealthShare)
• IRIS web port accessible (default 52773)

Quick Start

Until packages are published to npm, install by cloning the repository and building from source.

1. Clone and Build

git clone https://github.com/jbrandtmse/iris-execute-mcp-v2.git
cd iris-execute-mcp-v2
pnpm install
pnpm turbo run build

Requires: Node.js 18+ and pnpm 9+. Install pnpm with npm install -g pnpm if needed.

2. Set Environment Variables

All servers use the same environment variables:

3. Configure Your MCP Client

Point your MCP client at the built server using node and the local dist/index.js path. Replace /path/to/iris-execute-mcp-v2 with the actual path where you cloned the repo.

Claude Code (.mcp.json)

Create a .mcp.json file in your project root:

{
  "mcpServers": {
    "iris-dev-mcp": {
      "command": "node",
      "args": ["/path/to/iris-execute-mcp-v2/packages/iris-dev-mcp/dist/index.js"],
      "env": {
        "IRIS_HOST": "localhost",
        "IRIS_PORT": "52773",
        "IRIS_USERNAME": "_SYSTEM",
        "IRIS_PASSWORD": "SYS",
        "IRIS_NAMESPACE": "USER"
      }
    }
  }
}

Note: Replace "SYS" with your actual IRIS password. Avoid committing real credentials to version control.

Claude Desktop (claude_desktop_config.json)

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "iris-dev-mcp": {
      "command": "node",
      "args": ["/path/to/iris-execute-mcp-v2/packages/iris-dev-mcp/dist/index.js"],
      "env": {
        "IRIS_HOST": "localhost",
        "IRIS_PORT": "52773",
        "IRIS_USERNAME": "_SYSTEM",
        "IRIS_PASSWORD": "SYS",
        "IRIS_NAMESPACE": "USER"
      }
    }
  }
}

To add more servers, include additional entries under mcpServers using the same pattern. For example, to add admin tools:

{
  "mcpServers": {
    "iris-dev-mcp": {
      "command": "node",
      "args": ["/path/to/iris-execute-mcp-v2/packages/iris-dev-mcp/dist/index.js"],
      "env": { "IRIS_PASSWORD": "SYS" }
    },
    "iris-admin-mcp": {
      "command": "node",
      "args": ["/path/to/iris-execute-mcp-v2/packages/iris-admin-mcp/dist/index.js"],
      "env": { "IRIS_PASSWORD": "SYS" }
    }
  }
}

All server entry points:

4. Verify

Ask your AI assistant:

“List the IRIS namespaces” (with @iris-mcp/admin)

or

“Show me the globals in the USER namespace” (with @iris-mcp/dev)

If the assistant returns results from your IRIS instance, you are connected.

Architecture

All five servers share a common connection layer (@iris-mcp/shared) that handles:

• HTTP(S) connection to the IRIS web port using Basic Auth
• Session cookie reuse and CSRF token handling for efficient request batching
• Atelier REST API (built into IRIS) for document and code operations
• Custom REST dispatch (ExecuteMCPv2.REST.Dispatch) for execution, globals, security, interoperability, and analytics — auto-bootstrapped on first connection
• Built-in IRIS REST APIs for DocDB (/api/docdb/v1/) and REST management (/api/mgmnt/v2/)

Servers communicate over the MCP protocol (spec v2025-11-25) using either stdio or Streamable HTTP transport. Every tool returns both structuredContent (machine-readable) and text content (human-readable), and includes tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so clients can make informed decisions about tool usage.

┌────────────────────────────────────────────────────────┐
│                    MCP Client                          │
│          (Claude, Copilot, Cursor, etc.)               │
└──────────┬──────────┬──────────┬──────────┬───────────┘
           │          │          │          │
     ┌─────▼──┐ ┌─────▼──┐ ┌────▼───┐ ┌───▼────┐ ┌─────▼──┐
     │  dev   │ │ admin  │ │interop │ │  ops   │ │  data  │
     │(21)    │ │(22)    │ │(19)    │ │(16)    │ │(7)     │
     └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘
         │          │          │          │          │
         └──────────┴──────┬───┴──────────┴──────────┘
                           │
                  ┌────────▼────────┐
                  │  @iris-mcp/shared │
                  │  (HTTP client,   │
                  │   auth, config)  │
                  └────────┬────────┘
                           │  HTTP(S)
                  ┌────────▼────────┐
                  │  InterSystems   │
                  │     IRIS        │
                  └─────────────────┘

Per-Package Documentation

Each server has its own README with a complete tool reference:

• @iris-mcp/dev — Development Tools
• @iris-mcp/admin — Administration Tools
• @iris-mcp/interop — Interoperability Tools
• @iris-mcp/ops — Operations & Monitoring Tools
• @iris-mcp/data — Data & Analytics Tools

Known Limitations

Web Application Gateway Registration

When the MCP server auto-bootstraps its custom REST endpoint, it creates the web application via Security.Applications.Create(). However, this ObjectScript API call does not notify the CSP Gateway of the new application. As a result, requests to the new web app may return 404 until one of the following steps is taken:

1. Save via System Management Portal (SMP): Navigate to System Administration > Security > Applications > Web Applications, open the newly created web application, and click Save. This triggers the gateway registration automatically.
2. Restart the CSP Gateway: If SMP access is not available, restart the CSP Gateway service (or restart the IRIS instance) to force the gateway to reload its application table.

License

MIT

Contributing

Contributions are welcome. Please open an issue to discuss proposed changes before submitting a pull request.