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.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
Open the API tokens tab
Create new API token
Configure token details
Enable MCP
Create the token
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)
Copy MCP configuration
url, type, and headers:- URL: the
urlfield (the MCP endpoint Iru gives you). - X-API-Key: the
X-API-Keyentry insideheaders. Copy it exactly as Iru shows it, including thesk_live:prefix already in the snippet; MCP clients send it as theX-API-KeyHTTP header on each request. - X-MCP-Profile: the
X-MCP-Profileentry insideheaders, sent as theX-MCP-ProfileHTTP header.
headers exactly as Iru shows them. The X-API-Key value includes the sk_live: prefix already in the snippet.Select the confirmation checkbox
Click Next
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
- Configure to set permissions now (recommended).
- Skip to set permissions later.
Select endpoints (if you chose Configure)
- Expand a category (for example Blueprints) to see individual endpoints.
- Check the boxes for the endpoints you want to allow.
Save
Verify
Configure permissions later (if you skipped)
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
One-time secret display
Revocation is total
Revocation is total
Destructive actions
Destructive actions
Pagination
Pagination
Client-specific config
Client-specific config
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
Separate tokens by team or use case
Rotate on suspicion
url or headers values.Protect local config files
claude_desktop_config.json contains your url and header values. Do not commit it to source control or share it in chat logs.Protect MCP and API secrets
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. Register Iru by editingclaude_desktop_config.json with the url and headers values from your MCP configuration.Prerequisites
- In Iru, complete Copy your token and MCP configuration so you have
urlandheaders(X-API-Key,X-MCP-Profile). - Install Node.js 20+ from nodejs.org. The installer includes
npx, which Claude Desktop uses to run the Iru MCP connection.
- macOS
- Windows
Download and install Claude Desktop
Open Claude Desktop settings
Open Developer settings
Open the configuration file
Open claude_desktop_config.json
claude_desktop_config.json from that folder in your preferred text editor.{}. An existing file may already include mcpServers, preferences, or other settings. In that case, add only the "iru" block inside mcpServers and leave the rest unchanged. After the closing } of mcpServers, add a comma before the next top-level section (for example "preferences").Add the Iru MCP server entry
claude_desktop_config.json. The three highlighted lines are where you add your values from MCP configuration. Put your X-API-Key and X-MCP-Profile in env; when Claude Desktop starts, mcp-remote uses those values for the ${IRU_X_API_KEY} and ${IRU_X_MCP_PROFILE} placeholders in args.https://YOUR_TENANT.connect.iru.com/mcp-server/connector/kandji/toolswithurlfrom MCP configurationsk_live:YOUR_API_KEYwithX-API-Keyfrom MCP configurationYOUR_PROFILE_IDwithX-MCP-Profilefrom MCP configuration
Merge into an existing file
preferences or other settings already sit below mcpServers, your file should connect the sections like this. The highlighted line is the comma between mcpServers and the next top-level key:Save the file and restart Claude Desktop
claude_desktop_config.json, then fully quit Claude Desktop. Closing the window is not enough; select Claude → Quit Claude from the menu bar, then relaunch Claude Desktop.Claude Desktop loads MCP configuration on start-up.Verify the connection
Approve access when prompted
If something still fails
iru entry, whether the server is running, and any errors the host reports. See Troubleshooting below.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
General Iru MCP
The assistant says the token is invalid or authentication failed
The assistant says the token is invalid or authentication failed
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
Tools are missing or the assistant reports permission denied
Configuration looks correct in Iru but the client still fails
Configuration looks correct in Iru but the client still fails
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.Claude Desktop
Claude Desktop
Remote connector or network error (custom MCP URL)
Remote connector or network error (custom MCP URL)
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
Inspect the iru entry or read host errors
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 config file setup
stdio bridge (npx / mcp-remote) or config file setup
claude_desktop_config.json and confirm the iru entry’s MCP URL in args and the values in env still match url, X-API-Key, and X-MCP-Profile from MCP configuration (IRU_X_API_KEY must include the sk_live: prefix). The --header lines should still use ${IRU_X_API_KEY} and ${IRU_X_MCP_PROFILE}, not your raw key or profile. On macOS, command should be npx; on Windows, use the full path C:\Program Files\nodejs\npx.cmd. Save the file and fully quit Claude Desktop (Claude → Quit Claude on macOS, tray Quit on Windows) before reopening. On Windows, check logs\mcp-server-iru.log beside claude_desktop_config.json if iru still fails. See Add the Iru MCP to Claude Desktop.Cursor
Cursor
MCP does not load or iru stays off after editing settings
MCP does not load or iru stays off after editing settings
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.OpenAI Codex
OpenAI Codex
Add a project to use Codex (IDE extension)
Add a project to use Codex (IDE extension)
Codex: edit config.toml directly
Codex: edit config.toml directly
~/.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:MCP server does not connect or tools stay offline
MCP server does not connect or tools stay offline
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.