Iru MCP - Iru Docs

Introduction

The Model Context Protocol (MCP) is an open standard for connecting client applications (hosts) to MCP servers. Servers expose tools, resources, and prompts so AI assistants can take allowed actions in your environment through one consistent pattern, instead of building and maintaining a separate custom integration for every assistant or workflow you add. The Iru Model Context Protocol (MCP) server exposes the Iru Enterprise API surface, structured as MCP tools for AI assistants. Connect Cursor, Claude Desktop, OpenAI Codex, or other MCP-enabled clients to query devices, Blueprints, Library Items, and take allowed actions in natural language, without building your own Iru API integration. You can also combine Iru’s tools with tools from other vendors (for example ticketing, chat, or IAM) to create end-to-end workflows orchestrated in natural language. When Iru adds additional Enterprise API capabilities, those capabilities become available through MCP on the same permission model.

The Enterprise API (and the MCP backed by it) applies across Iru areas that surface that API, including Endpoint and other products such as Vulnerability Management and Endpoint Detection and Response, depending on your tenant and entitlements.

For REST usage (HTTP APIs and bearer tokens outside MCP), see the Iru API Overview.

Before you begin

You need an Iru admin account with permission to create and manage API tokens in Access, as described in the Iru API Overview.
You need a supported MCP client (such as Claude Desktop, Cursor, or Codex).

Create an API token with MCP

Use Generate an API Token in the Iru API Overview for the full UI walkthrough (screenshots, Copy Token, Next, Configure / Skip, permission grids). The steps here match that article; you must turn on Enable MCP before Create so Iru issues MCP configuration for this token.

Open Access

Click your name at the bottom of the left navigation, then select Access.

Open the API tokens tab

In Access, click the API tokens tab.

Create new API token

Click Add Token to create a new API token.

Configure token details

Provide a Name and a Description for your API token.

Enable MCP

Turn on Enable MCP before you click Create. For MCP, this step is required; if Enable MCP is off, you get an Enterprise API token without MCP access or MCP configuration.

Create the token

Click Create.

API rate limits: The Iru Endpoint Management API enforces 10,000 requests per hour per customer. MCP calls authenticate with the X-API-Key value under headers in MCP configuration for that token and count toward the same tenant hourly limit as direct REST usage and other integrations. All API tokens in your tenant share that limit. For background and troubleshooting, see Considerations in the Iru API Overview and the Iru Endpoint Management API documentation.

Copy Your Token and MCP Configuration

After you create the token, Iru shows a one-time success screen: Your token has been successfully created! Copy what you need, store it safely, and remember you will not see it again. Run the steps below in order; MCP configuration means the JSON from Copy MCP configuration in step 2.

Copy the API token (optional for non-MCP API use)

For REST or custom scripts, use Copy beside the API token on the success screen. That value is not used for MCP.

Copy MCP configuration

In MCP configuration, review the JSON, then use Copy MCP configuration. Iru’s snippet is built around url, type, and headers:

URL: the url field (the MCP endpoint Iru gives you).
X-API-Key: the X-API-Key entry inside headers. Copy it exactly as Iru shows it, including the sk_live: prefix already in the snippet; MCP clients send it as the X-API-Key HTTP header on each request.
X-MCP-Profile: the X-MCP-Profile entry inside headers, sent as the X-MCP-Profile HTTP header.

Copy MCP configuration is the JSON for MCP. Use the values from headers exactly as Iru shows them. The X-API-Key value includes the sk_live: prefix already in the snippet.

Placeholder example only:

mcp.json

{
  "mcpServers": {
    "iru": {
      "url": "https://YOUR_TENANT.connect.iru.dev/mcp-server/connector/YOUR_CONNECTOR_SLUG/tools",
      "type": "http",
      "headers": {
        "X-API-Key": "sk_live:YOUR_API_KEY",
        "X-MCP-Profile": "YOUR_PROFILE_ID"
      }
    }
  }
}

Select the confirmation checkbox

Select the confirmation checkbox: I have copied the token and MCP configuration and understand that I will not be able to see these details again.

Click Next

Click Next.

If you lose the token or configuration, revoke the token and create a new one.

Configure API permissions

After you click Next, you’ll see a Manage API Permissions screen. These permissions control which Enterprise API endpoints the MCP can access.

Configure now or skip

Choose one of the following:

Configure to set permissions now (recommended).
Skip to set permissions later.

Select endpoints (if you chose Configure)

If you clicked Configure, use the permissions list to select what this token can do:

Expand a category (for example Blueprints) to see individual endpoints.
Check the boxes for the endpoints you want to allow.

Save

When you’re done, click Save.

Verify

Verify the token shows MCP enabled: Yes if you turned on MCP at creation time, and that the permissions you selected are enabled.

Configure permissions later (if you skipped)

If you skipped permission setup, you can configure permissions later by opening the token, clicking Edit, then selecting the permissions and clicking Save.

Revoke an API token

Revoke the token in Access like any other API token. Use Revoke a Token in Iru API Overview for the steps and Activity notes.

Considerations

One-time secret display

The REST API token from Copy and the MCP configuration JSON are each shown only once on the success screen at creation time.

Revocation is total

Revoking the token stops API and MCP access that relied on it.

Destructive actions

For destructive operations (for example erase, delete, lock), your assistant should summarize the impact and require your explicit approval before executing, unless you’ve added that action to an allowlist for the MCP. Follow your organization’s change-management rules.

Pagination

Large list responses are paginated. Ask the assistant to refine filters, move to the next page, or export when you need the full dataset without pulling every row into the chat.

Client-specific config

MCP configuration is JSON with url, type, and headers. headers holds X-API-Key and X-MCP-Profile, which together are what Iru expects on each MCP request. Point your client at url and forward those two header values unchanged. The X-API-Key value includes the sk_live: prefix already in the snippet.

Best practices

Use least privilege

Create a token with only the Enterprise API scopes your automation needs, then enable MCP on that token.

Separate tokens by team or use case

For example, use a read-focused token for reporting assistants and a narrower operational token for remediation workflows.

Rotate on suspicion

If MCP configuration leaked, revoke the token in Iru and issue a new one; update every MCP client that still has the old url or headers values.

Prefer environment variables

For the Claude Desktop setup scripts, keep IRU_MCP_URL, IRU_X_API_KEY, and IRU_X_MCP_PROFILE (and the MCP configuration strings they mirror) out of source control; use OS or IDE secrets where you can.

Protect MCP and API secrets

Treat MCP configuration and any REST token you Copy for non-MCP use as secrets. Store them in a password manager or secure vault, not in chat logs or screenshots.

Add the Iru MCP to Your MCP Client

Choose a client, then follow the steps for that host.

Claude Desktop
Cursor
OpenAI Codex

Add the Iru MCP to Claude Desktop

Claude Desktop is Anthropic’s desktop app for chatting with Claude. The steps below use a setup script from the Iru Support GitHub repository to register Iru in Claude Desktop using your MCP configuration.

macOS
Windows

Prepare values from Iru

In Iru, complete Copy your token and MCP configuration so you have url and headers (X-API-Key, X-MCP-Profile).

Download and install Claude Desktop

Download Claude Desktop for macOS from Anthropic, install the app, and sign in: Download Claude.

Download the setup script

Copy iru-mcp-claude-desktop-macos.zsh from the Iru Support GitHub repository (GitHub Link). Save it where you prefer, make it executable if needed with chmod +x.

Install Node.js

Install Node.js 20+ from https://nodejs.org so npx works.

Install jq

Install jq. If you use Homebrew, run:

Terminal

brew install jq

Open Terminal

Open Terminal.

Set environment variables

Replace PASTE_MCP_CONFIGURATION_URL with url and PASTE_MCP_CONFIGURATION_X_MCP_PROFILE with X-MCP-Profile from MCP configuration. Replace PASTE_MCP_CONFIGURATION_X_API_KEY with the X-API-Key value (paste the full string, including the sk_live: prefix already in the snippet), then run the block:

Terminal

export IRU_MCP_URL="PASTE_MCP_CONFIGURATION_URL"
export IRU_X_API_KEY="PASTE_MCP_CONFIGURATION_X_API_KEY"
export IRU_X_MCP_PROFILE="PASTE_MCP_CONFIGURATION_X_MCP_PROFILE"

Run the script

Run iru-mcp-claude-desktop-macos.zsh with zsh, using the path where you saved the file:

Terminal

zsh ~/Downloads/iru-mcp-claude-desktop-macos.zsh

Restart Claude Desktop

Fully quit Claude Desktop (Claude → Quit Claude), then open it again. Closing the window is not enough; use Quit so the app exits completely.

Open a new chat

Open a new chat in Claude Desktop.

Choose Ask Iru

Click the + button beside the composer, choose Ask Iru, then start your message so Claude can use the Iru MCP.

Approve access when prompted

Claude will prompt before each Iru MCP tool use. Choose Allow once for that run only, or Always allow when you want fewer prompts for similar actions. Approve when you want reads or allowed changes in Iru; decline if you do not want the tool to run.

Turn the Iru connector on or off

To enable or disable the integration without changing your saved configuration, click +, open Connectors, and use the Iru toggle.

If something still fails

In Claude Desktop, open Settings → Developer to review the iru entry, whether the server is running, and any errors the host reports.

Prepare values from Iru

In Iru, complete Copy your token and MCP configuration so you have url and headers (X-API-Key, X-MCP-Profile).

Download and install Claude Desktop

Download Claude Desktop for Windows from Anthropic, install the app, and sign in: Download Claude.

Download the setup script

Copy iru-mcp-claude-desktop-windows.ps1 from the Iru Support GitHub repository (GitHub Link). Save it in the folder you will cd into in the steps below.

Install Node.js

Install Node.js 20+ from https://nodejs.org so npx works.

Open PowerShell

Open Windows PowerShell 5.1 or newer. You don’t need to run as administrator for these steps unless your environment requires it for another reason.

Allow scripts for this session

In that same window, run this so local scripts can execute only in this PowerShell session. It does not change machine-wide or user-wide policy; when you close the window, your normal execution policy applies again.

Terminal

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force

Go to the script folder

Go to the folder where iru-mcp-claude-desktop-windows.ps1 is:

Terminal

cd "FULL\PATH\TO\FOLDER_WITH_THE_SCRIPT"

Set IRU_MCP_URL

Replace PASTE_MCP_CONFIGURATION_URL with url from MCP configuration, then run:

Terminal

$env:IRU_MCP_URL = "PASTE_MCP_CONFIGURATION_URL"

Set IRU_X_API_KEY

Replace PASTE_MCP_CONFIGURATION_X_API_KEY with the X-API-Key value from MCP configuration (paste the full string, including the sk_live: prefix already in the snippet), then run:

Terminal

$env:IRU_X_API_KEY = "PASTE_MCP_CONFIGURATION_X_API_KEY"

Set IRU_X_MCP_PROFILE

Replace PASTE_MCP_CONFIGURATION_X_MCP_PROFILE with X-MCP-Profile, then run:

Terminal

$env:IRU_X_MCP_PROFILE = "PASTE_MCP_CONFIGURATION_X_MCP_PROFILE"

Run the script

Run:

Terminal

.\iru-mcp-claude-desktop-windows.ps1

Restart Claude Desktop

Fully quit Claude Desktop (right-click the Claude icon in the system tray → Quit), then open it again. Closing the window is not enough; use Quit so the app exits completely.

Open a new chat

Open a new chat in Claude Desktop.

Choose Ask Iru

Click the + button beside the composer, choose Ask Iru, then start your message so Claude can use the Iru MCP.

Approve access when prompted

Turn the Iru connector on or off

To enable or disable the integration without changing your saved configuration, click +, open Connectors, and use the Iru toggle.

If something still fails

In Claude Desktop, open Settings → Developer to review the iru entry. When the MCP server runs, Claude may also write logs\mcp-server-iru.log next to claude_desktop_config.json in the Claude Desktop app data folder for your install.

Add the Iru MCP to Cursor

Cursor is an AI-native code editor for writing and editing software with built-in assistance. The Cursor desktop app is available on macOS, Windows, and Linux. Add Iru under Tools & MCP so you can use your tenant’s tools from the editor.

Prepare values from Iru

In Iru, complete Copy your token and MCP configuration so you have url and headers (X-API-Key, X-MCP-Profile).

Download and install Cursor

Download Cursor for your platform, install the app, and sign in: Download Cursor.

Open MCP settings

Open Cursor MCP Settings:

macOS: Cursor → Settings → Cursor Settings, then Tools & MCP.
Windows/Linux: File → Preferences → Cursor Settings, then Tools & MCP.

Add Custom MCP

Click Add Custom MCP.

Paste MCP configuration

The mcp.json file opens in the editor. How you paste depends on whether other MCP servers are already defined. Cursor starts with a placeholder like this:

mcp.json

{
  "mcpServers": {}
}

New setup

Replace the entire contents of mcp.json with the complete MCP configuration you copied from Copy MCP configuration when you created the token. Select everything in the file (including Cursor’s placeholder), paste, and leave only Iru’s JSON in mcp.json. Do not remove the sk_live: prefix from X-API-Key in headers.

Existing MCP servers

If mcpServers already lists other servers you want to keep, do not replace the whole mcp.json file. Add only the iru block from MCP configuration. Copy from "iru": { through the closing } for that server (the second } after headers). Add a comma after the closing } of the server entry that comes immediately before iru. Keep X-API-Key exactly as Iru shows it, including the sk_live: prefix already in the snippet.Example when another server is already configured (highlighted lines show the trailing comma and the iru block to copy and paste into the mcp.json file):

mcp.json

{
  "mcpServers": {
    "previous-mcp-server": {
      "url": "https://example.com/mcp",
      "type": "http",
      "headers": {
        "X-API-Key": "sk_live:YOUR_OTHER_KEY",
        "X-MCP-Profile": "YOUR_OTHER_PROFILE"
      }
    },
    "iru": {
      "url": "https://YOUR_TENANT.connect.iru.dev/mcp-server/connector/YOUR_CONNECTOR_SLUG/tools",
      "type": "http",
      "headers": {
        "X-API-Key": "sk_live:YOUR_API_KEY",
        "X-MCP-Profile": "YOUR_PROFILE_ID"
      }
    }
  }
}

Save the configuration

Cursor does not save mcp.json automatically after you paste. Save the file manually before you quit or restart:

macOS: Command+S
Windows/Linux: Ctrl+S, or File → Save

Restart Cursor

Fully quit Cursor, then reopen it. Cursor loads MCP on startup.

Confirm

Return to Tools & MCP. Confirm iru appears and the toggle shows enabled.

For more on using MCP in Cursor, see Model Context Protocol (MCP) in Cursor.

Add the Iru MCP to OpenAI Codex

OpenAI Codex is OpenAI’s coding agent for building and changing software with AI. Use the Codex Desktop App or the Codex extension in VS Code to register Iru as an MCP server and work with your tenant from chat.

Desktop App
IDE extension

Codex Desktop App

The Codex Desktop App is available on macOS and Windows. For platform support, install options (including Intel Mac builds), and other app requirements, see the Codex app documentation on OpenAI Developers.

Prepare values from Iru

In Iru, complete Copy your token and MCP configuration so you have url and headers (X-API-Key, X-MCP-Profile).

Download and install Codex

Download the Codex Desktop App and install it: Codex.

Open Codex and sign in with your ChatGPT account or an OpenAI API key. Codex is included with eligible ChatGPT plans. See Open Codex and sign in in the Codex app documentation.

Open Settings

In Codex, go to Settings.

Open MCP servers

Select MCP servers.

Add server

Click + Add server.

Name

Enter Iru MCP for Name.

Transport

Select Streamable HTTP.

URL

Enter the url value from MCP configuration in URL.

Header for X-API-Key

Under Headers, set Key to X-API-Key and Value to the X-API-Key entry from headers in MCP configuration, copied exactly as Iru shows it, including the sk_live: prefix already in the snippet.

Header for X-MCP-Profile

Click + Add header. Set Key to X-MCP-Profile and Value to the X-MCP-Profile entry from headers in MCP configuration.

Save

Click Save.

Restart Codex

Fully quit Codex, then open it again so it reloads MCP settings.

Try Iru in chat

Start a new chat and ask Codex a question about an Enterprise API area your token has permission to use (for example devices or Blueprints).

Codex IDE extension

The Codex IDE extension runs OpenAI’s coding agent in your editor. Add Iru through the extension’s MCP settings.

Prepare values from Iru

In Iru, complete Copy your token and MCP configuration so you have url and headers (X-API-Key, X-MCP-Profile).

Install Visual Studio Code

Install Visual Studio Code if needed. VS Code supports macOS, Windows, and Linux.

Install the Codex extension

Install the Codex extension from the Visual Studio Marketplace. The extension also works in other VS Code–compatible editors (for example Cursor); menus and platform support may differ. See the Codex IDE extension documentation for install options.

Open the Codex sidebar

Open the Codex sidebar using the OpenAI logo in the activity bar, Open Codex Sidebar, or by toggling the secondary sidebar and selecting the Codex tab.

Click Sign in with ChatGPT and authenticate. Codex is included with eligible ChatGPT plans. Follow any prompts to finish setup.

Open Codex settings

In the Codex sidebar, click the gear icon, then Codex settings.

Open MCP servers

Click MCP servers.

Add server

Click + Add server.

Name

Enter Iru MCP for Name.

Transport

Select Streamable HTTP.

URL

Enter the url value from MCP configuration in URL.

Header for X-API-Key

Header for X-MCP-Profile

Click + Add header. Set Key to X-MCP-Profile and Value to the X-MCP-Profile entry from headers in MCP configuration.

Save

Click Save.

Restart the extension

If Codex shows Restart extension, click it so MCP settings reload.

Try Iru in chat

In the Codex sidebar, start a conversation and ask about an Enterprise API area your token has permission to use (for example devices or Blueprints).

Troubleshooting

For MCP-wide help (log locations, configuration checks, MCP Inspector, and client debugging beyond the Iru-specific notes below), see the Model Context Protocol debugging guide.

General Iru MCP

The assistant says the token is invalid or authentication failed

Re-check url and headers (X-API-Key, X-MCP-Profile) in MCP configuration. Remove stray spaces. X-API-Key must match the full value from Iru, including the sk_live: prefix already in the snippet. If the backing token was rotated or revoked, create a new one and refresh every client.

Tools are missing or the assistant reports permission denied

The Enterprise API scopes on the token can block those operations. Edit the token’s API permissions in Access, or create a new token with the scopes you need.

Configuration looks correct in Iru but the client still fails

Confirm MCP configuration in the client matches url and headers from Iru, then fully quit and restart the host app so it reloads MCP settings. If the problem persists, use the Model Context Protocol debugging guide for host logs, JSON validation, and testing with MCP Inspector.

Cursor

MCP does not load or iru stays off after editing settings

Fully quit Cursor, then reopen it; Cursor loads MCP on startup. If mcp.json still fails to load, confirm valid JSON. For a new setup, confirm you replaced the entire file with MCP configuration; if you merged into existing servers, confirm the iru block and commas are correct. Check that url, X-API-Key, and X-MCP-Profile match MCP configuration (see Add the Iru MCP to Cursor). X-API-Key must include the sk_live: prefix already in the snippet. For deeper host issues, see the Model Context Protocol debugging guide.

Claude Desktop

Remote connector or network error (custom MCP URL)

Custom connectors reach your MCP server from Anthropic’s infrastructure. Confirm that url in MCP configuration is correct, that the service is on the public internet, and that any corporate firewall allows Anthropic’s IP ranges. See Get started with custom connectors using remote MCP and Anthropic IP addresses.

Inspect the iru entry or read host errors

In Claude Desktop, open Settings, then Developer. There you can review the iru server configuration, see whether the server is running, and read any errors the host reports. For Claude log paths, DevTools, and related steps, see Debugging in Claude Desktop in the Model Context Protocol debugging guide.

stdio bridge (npx / mcp-remote) or script setup

Confirm Node.js 20+, npx, and (on macOS) jq are installed, that IRU_MCP_URL, IRU_X_API_KEY, and IRU_X_MCP_PROFILE still match url, X-API-Key, and X-MCP-Profile from MCP configuration (IRU_X_API_KEY must include the sk_live: prefix already in the snippet), then rerun the setup script and fully quit Claude Desktop (Claude → Quit Claude on macOS, tray Quit on Windows) before reopening. On Windows, the script resolves a real npx path when a version-manager shim would break MCP; check logs\mcp-server-iru.log beside claude_desktop_config.json if iru still fails. See Add the Iru MCP to Claude Desktop.

OpenAI Codex

Add a project to use Codex (IDE extension)

If Codex shows Add a project to use Codex when you chat, open or create a project folder in the editor first, then return to the Codex sidebar.

Codex: edit config.toml directly

If you cannot save or change MCP settings in the UI, edit ~/.codex/config.toml directly. Per Model Context Protocol in Codex, the CLI, Codex IDE extension, and Codex Desktop App share this file. See Codex IDE extension or Codex Desktop App for the UI setup flows.Open ~/.codex/config.toml in a text editor. The ~ is your home folder (for example /Users/your-user-name/.codex/config.toml on macOS).Set url and http_headers from MCP configuration, copied exactly as Iru shows them. The X-API-Key value in http_headers includes the sk_live: prefix already in the snippet. Use Iru MCP as the server name. In config.toml, the table name after mcp_servers. must match how Codex stored that server (often derived from Iru MCP, for example iru_mcp).Example for Iru MCP:

config.toml

[mcp_servers.iru_mcp]
enabled = true
url = "https://YOUR_TENANT.connect.iru.dev/mcp-server/connector/YOUR_CONNECTOR_SLUG/tools"
http_headers = { "X-API-Key" = "sk_live:YOUR_API_KEY", "X-MCP-Profile" = "YOUR_PROFILE_ID" }

Save the file, then fully quit Codex or restart your editor so MCP settings reload.

MCP server does not connect or tools stay offline

Confirm Iru MCP is enabled in Codex MCP settings, url and headers match MCP configuration (X-API-Key must include the sk_live: prefix already in the snippet), then fully quit the host app and reopen it so Codex reloads MCP. For the Codex IDE extension, this means quitting the editor; for the Codex Desktop App, quit Codex completely. For transport-level debugging, see the Model Context Protocol debugging guide.

Iru API Overview

REST APIs, tokens, permissions, and Activity for the Enterprise API that MCP exposes as tools.

How to Set Up the Iru Endpoint API in Postman

Import the published collection and send authenticated requests outside MCP.

Iru Endpoint Management API reference

Browse endpoints, parameters, and request and response examples for the underlying API.

Integrating Third-Party Apps Using the Iru Endpoint API

Connect third-party products and map the API permissions each integration needs.

​Introduction

​Before you begin

​Create an API token with MCP

​Copy Your Token and MCP Configuration

​Configure API permissions

​Revoke an API token

​Considerations

​Best practices

Use least privilege

Separate tokens by team or use case

Rotate on suspicion

Prefer environment variables

Protect MCP and API secrets

​Add the Iru MCP to Your MCP Client

​Add the Iru MCP to Claude Desktop

​Add the Iru MCP to Cursor

​Add the Iru MCP to OpenAI Codex

​Codex Desktop App

​Codex IDE extension

​Troubleshooting

​Related articles

Iru API Overview

How to Set Up the Iru Endpoint API in Postman

Iru Endpoint Management API reference

Integrating Third-Party Apps Using the Iru Endpoint API

Introduction

Before you begin

Create an API token with MCP

Copy Your Token and MCP Configuration

Configure API permissions

Revoke an API token

Considerations

Best practices

Add the Iru MCP to Your MCP Client

Add the Iru MCP to Claude Desktop

Add the Iru MCP to Cursor

Add the Iru MCP to OpenAI Codex

Codex Desktop App

Codex IDE extension

Troubleshooting

Related articles