read thedocs.

ImmyBot is a Windows and macOS software-deployment and endpoint-automation platform for MSPs. Connecting it to StackJack gives your AI assistant a family of 555 immy_ MCP tools — MCP (Model Context Protocol) tools are the standardized commands an AI assistant can call through StackJack. With them, your AI can:

• Inventory managed computers, their software and detected applications, agent status, and per-tenant fleet counts
• Manage software and scripts — global and local software packages and versions, PowerShell scripts and metascripts, Chocolatey lookups, and software licenses
• Run deployments and maintenance — deployments (target assignments), maintenance sessions and actions, maintenance and inventory tasks, and schedules
• Organize customers — tenants, tags, persons, users, and role-based access (RBAC)
• Wire up integrations — provider links (RMM/PSA), provider clients and agents, and dynamic provider types
• Act (on Pro plans) — create, update, and delete across those areas; run scripts and maintenance on endpoints; onboard and offboard computers; and manage tenants, deployments, and RBAC

How StackJack authenticates to ImmyBot

ImmyBot is the one connector that authenticates through your own Microsoft Entra ID (Azure AD) rather than the vendor's login. You register an application in Entra, grant it access to your ImmyBot instance's API, and give StackJack four values. StackJack mints a short-lived access token from Microsoft and calls your ImmyBot instance directly — there is no ImmyBot login to share, and no refresh token to manage.

The four values StackJack needs:

• Azure Tenant (ID or domain) — your Microsoft tenant, entered as either the tenant ID (a GUID) or your Azure domain (e.g. contoso.onmicrosoft.com).
• Application (Client) ID — the Entra app registration's Application (client) ID.
• Client Secret — a client secret value from that app registration.
• Instance URL — your ImmyBot instance URL. This is usually https://your-subdomain.immy.bot, but if your instance is on a custom domain or a self-hosted host (for example https://immy.yourcompany.com), enter that host instead. StackJack accepts any well-formed https:// host — it does not have to end in .immy.bot — as long as it uses HTTPS and carries no embedded username/password.

Access tokens are valid for about 60 minutes and StackJack re-mints them automatically as needed. There is no refresh token — recovery is simply a fresh token request. The application acts against your ImmyBot instance with exactly the access you grant it: read tools need read access, and write or destructive tools need the corresponding write access. A permissions error from one tool means the app lacks that specific access, not an account-wide block.

Before you begin

• In StackJack: you need a role that can manage connectors (tenant Owner, a co-owner, or an Administrator).
• In Microsoft Entra ID: access to the same Microsoft tenant your ImmyBot instance uses, sufficient to create an app registration, add a client secret, and complete admin consent.
• Your ImmyBot instance URL — usually https://your-subdomain.immy.bot, or your custom / self-hosted host if you use one.

Step 1 — Register an application in Microsoft Entra ID

1. In the Azure portal for the same Microsoft tenant your ImmyBot instance uses, go to Microsoft Entra ID → App registrations → New registration.
2. Give it a name (for example, "StackJack") and register it.

Step 2 — Grant the app access to your ImmyBot API and consent

1. Following the ImmyBot API documentation, grant the new app application permission to your ImmyBot instance's API.
2. Complete any required admin consent so the app can call ImmyBot on its own behalf (app-only, with no user signed in).

Step 3 — Create a client secret

1. On the app registration, go to Certificates & secrets → New client secret.
2. Copy the secret VALUE immediately — Azure shows it only once.

Step 4 — Add the credentials in StackJack

1. In the StackJack portal, open Connectors.
2. Find the ImmyBot card. Click How To Connect for these steps inline, or Configure to enter the credentials.
3. Fill in the four fields:
   • Azure Tenant (ID or domain) — the tenant GUID or your Azure domain.
   • Application (Client) ID — the app registration's Application (client) ID.
   • Client Secret — the secret value you copied.
   • Instance URL — https://your-subdomain.immy.bot.
4. Click Save.

What happens when you save

• If you entered an Azure domain, StackJack looks up its tenant ID for you. If the domain can't be resolved, the save is rejected so a bad value is never stored — re-check the domain and try again.
• The credentials are stored encrypted in Azure Key Vault — never in the StackJack database, and never shown back to you.
• If this is the first time you configure ImmyBot, a Free-tier subscription for the connector is created automatically so its Free tools work right away.
• StackJack live-validates the credentials by minting a token and making a cheap authenticated read. Validation never blocks the save: you'll either see a success confirmation or a "saved but validation failed" warning with the reason.
• The connector card shows the current connection and validity status from then on.

Plans and available tools

• Free includes the 264 read-only tools: list, get, search, count, and preview across computers and inventory, software and scripts, deployments, maintenance sessions and actions, tenants and tags, persons and users, provider links and agents, RBAC, schedules, media, notifications, billing, and system status.
• Pro adds the 291 write and action tools: create/update/delete across those areas, plus running scripts and maintenance on endpoints, onboarding and offboarding computers, and managing tenants, deployments, provider integrations, and RBAC.
• Business offers the same tool set as Pro with a higher monthly call quota.

ImmyBot API access is app-only — there is no per-user sign-in, so all AI traffic authenticates as the single registered Entra application and there is no per-user attribution. Current pricing and quotas are shown in the portal's Billing page and at checkout.

Safety note — endpoint actions. Some ImmyBot tools run scripts on, reboot, or re-image managed endpoints, run maintenance, or change instance-wide settings — for example running a script (immy_scripts_run), running maintenance (immy_run_immy_service), or restarting the backend (immy_system_restart_backend). These are marked as write/destructive so your AI must get approval before running them. Scope your AI's access deliberately: use the tool selections on the MCP Setup page and the Permissions page to enable only the actions you want an AI to take.

Spreadsheet exports. A few list tools (for example, exporting computers or tenant software inventory) return the ImmyBot spreadsheet as a short-lived, read-only download link rather than inline data. Open the link promptly — it expires. Re-run the tool to get a fresh link.

Rate limits

ImmyBot publishes no numeric API quota. StackJack applies a conservative per-tenant pace (about 300 requests per minute) and honors any rate-limit backoff, so bursts of tool calls queue briefly instead of failing — a long multi-page inventory read may simply take a little longer.

Rotating or replacing the credentials

The Entra client secret is the recovery secret. If you rotate or remove the client secret in Entra — or the secret expires — the stored credential becomes invalid. To restore access, open Connectors → ImmyBot → Configure in StackJack and enter the new client secret value (re-confirm the other fields if needed), then Save.

Troubleshooting