ImmyBot API Patterns

ImmyBot MCP Tools & API Patterns

Overview

ImmyBot is a desired-state software deployment platform for Windows endpoints. You configure what should be installed at the tenant or computer level, then a maintenance session reconciles the live state to the desired state. The MCP surface mirrors that model — listing and configuring desired state is one set of tools; running and inspecting maintenance sessions is another.

Anti-triggers

• Entra ID app registrations, consent, or Graph scopes in general — ImmyBot happens to authenticate with an Entra client-credentials app, but this skill covers only the four ImmyBot credential fields. Questions about Entra apps themselves are microsoft-graph-connection.
• What a maintenance session actually does — the polling cadence is here; session scope, reboot behaviour, and cancel semantics are immybot-maintenance-sessions.

Connection & Authentication

ImmyBot uses Microsoft Entra ID (Azure AD) OAuth 2.0 client credentials. Four fields are required:

The gateway exchanges these for a token automatically. Token cache is managed gateway-side; you should not need to think about token refresh.

Navigation Tools

Functional Tool Surface

Tools follow immybot_<domain>_<action>. Domains:

• computers - Enrolled Windows endpoints
• software - Software catalog (per-tenant + global)
• deployments - Desired-state assignments (the "what should be installed")
• scripts - PowerShell scripts and execution history
• tenants - MSP-level tenant scoping
• maintenance_sessions - The reconciliation runs (active, paused, etc.)
• tasks - Lower-level work units inside sessions

The Two-Step Desired-State Model

This is the most important concept in ImmyBot. Software does not get installed by a single API call. Instead:

1. Configure desired state — Use immybot_deployments_create (or update an existing deployment) to assert: "Software X should be installed at version Y on this scope."
2. Reconcile — A maintenance session runs (either on schedule, or triggered via immybot_maintenance_sessions_start) and brings the endpoints in scope into compliance with the desired state.

If you skip step 2, nothing happens on the endpoint. If you skip step 1 and try to "install software directly," there is no API for that — the platform is desired-state by design.

Destructive Operations

The following tools mutate live customer infrastructure. Always confirm with a human before invoking:

• immybot_scripts_run - Executes a PowerShell script on endpoints
• immybot_deployments_trigger - Forces deployment evaluation
• immybot_software_install - Triggers software install via desired state
• immybot_maintenance_sessions_start - Starts a reconciliation run

For all four, log who approved, the scope (computer / tenant), and the expected outcome before calling.

Polling Tasks and Sessions

immybot_maintenance_sessions_start and similar tools return quickly with a session/task ID. Actual progress is observed by polling:

• immybot_maintenance_sessions_get - Snapshot of one session
• immybot_maintenance_sessions_logs - Log lines so far
• immybot_maintenance_sessions_results - Final outcome
• immybot_tasks_get, immybot_tasks_logs - Lower-level task detail

Reasonable cadence: 10-15s while a session is running, stop once it reaches a terminal state.

Error Handling

Best Practices

• For MSP work, scope by tenant first (immybot_tenants_get) and pivot down — never modify deployments without confirming the tenant.
• Always pull immybot_maintenance_sessions_results after a session to see which endpoints succeeded vs failed.

Related Skills

• software-deployment - Primary skill, the desired-state workflow