Connect an AI Client

ImmyBot includes a built-in MCP server, so you can connect AI tools like Claude, Claude Code, Cursor, or ChatGPT/Codex directly to your instance and ask them, in plain English, to look things up or take action — "find every computer that hasn’t checked in this week," "list what’s failing patch compliance in the Acme tenant," "reboot every offline agent in this tenant" — and the connected AI will find the right commands and run them against your instance for you.

How it works, in short

• Everything a connected AI tool does runs under your own permissions, using either your ImmyBot sign-in or a personal access token you generate. If you couldn’t do something yourself in ImmyBot, the AI can’t do it either.
• Every action taken through MCP shows up in ImmyBot’s audit log under your name, exactly as if you’d done it yourself.
• The AI doesn’t get a fixed, hardcoded list of things it can do. It uses two lookup tools (search and describe) to discover the right PowerShell commands or API calls for the task, then runs them through a sandboxed scripting engine — the same sandbox ImmyBot’s Script Editor and computer Terminal already use.
• This capability is sometimes referred to as "code mode" — the AI is effectively writing and running short PowerShell scripts against your instance on your behalf, rather than calling a small set of canned actions.

Prerequisites

MCP requires ImmyBot 0.85.0 or later.

To do this…	You need…
Connect an AI tool at all	An MSP-level account whose role includes Use personal access tokens over MCP and/or Use OAuth over MCP — the two permissions under the MCP section of the role editor. The built-in System Administrator (Legacy) role already includes both; custom roles need an administrator to add them.
Turn MCP on or off for the instance	The Manage Application Preferences permission
Create your own personal access token	The Create Personal Access Tokens permission
View or revoke other users’ tokens	The Revoke Others’ Personal Access Tokens permission (admin-only)
Actually have a connected AI tool run something (the execute/get/cancel/session tools)	The Run Arbitrary Scripts permission on whichever tenant/computer the AI is targeting — the same permission that gates ad-hoc runs from the Script Editor and the computer Terminal tab

MCP is an instance-wide setting, not a per-tenant one — once it’s turned on, any tenant your account can already reach is reachable through MCP, subject to your normal permissions.

---

Step 1: Turn on the MCP server

1. Go to Show more → MCP and toggle on the MCP Server.

   If you don’t see a toggle you can change, you don’t have the Manage Application Preferences permission — ask an ImmyBot administrator to enable it, or to grant you that permission.

2. Once enabled, a Connector URL panel appears with your instance’s MCP endpoint URL (something like https://yourinstance.immy.bot/mcp). You’ll paste this into your MCP client in Step 3.

Step 2: Choose how your AI client will sign in

ImmyBot accepts two kinds of credential at the MCP address. Pick the one your client supports — the ImmyBot sign-in and Personal access token cards on the MCP page show what’s available to you.

	ImmyBot sign-in (OAuth)	Personal access token
Best for	Chat apps with a connector wizard: claude.ai, the Claude desktop app, ChatGPT	Command-line and developer tools: Claude Code, Codex, Cursor, VS Code
How it works	Your client opens a browser window and you sign in with your ImmyBot account	You create a token in ImmyBot and paste it into your client’s settings
Permission needed	Use OAuth over MCP	Use personal access tokens over MCP, plus Create Personal Access Tokens to create the token
Secrets to manage	None	One token, shown once
Availability	Depends on your instance — the card shows Enabled or Not enabled. If it says Not enabled, contact ImmyBot support	Always available when MCP is on

Some clients support both. Prefer ImmyBot sign-in where you can: there’s nothing to copy, nothing to store, and access ends when you sign out or your account is disabled.

Creating a personal access token

Skip this if your client will use ImmyBot sign-in.

1. Still on Show more → MCP, find the Personal access token card and click Create token.

2. Give the token a label so you can identify it later (e.g. “Claude Code — laptop”), and choose an expiration: Never, 30, 60, or 90 days, or a custom date.

3. Click Create token. Your token is shown once — copy it now.

You can see and revoke your own tokens at any time from the same page. Revoking a token takes effect immediately and can’t be undone — any client using it will need a new token to reconnect.

Step 3: Connect an MCP client

Pick the client you’re using below. In all cases you’ll need the Connector URL from Step 1 and — unless your client uses ImmyBot sign-in — the token from Step 2.

Claude (claude.ai and the Claude desktop app)

Uses ImmyBot sign-in — no config file, no token.

1. In Claude, open Customize > Connectors.
2. Click Add custom connector.
3. Paste your connector URL (for example https://yourinstance.immy.bot/mcp) and continue. Claude checks the address and pre-fills the authentication settings it detects — you should see authentication marked as Detected.
4. Leave the OAuth client settings at their defaults; ImmyBot doesn’t need a client ID or secret from you.
5. Click Add, then Connect. A browser window opens — sign in with the Microsoft account you use for ImmyBot.
6. Start a new chat and make sure the ImmyBot connector is switched on in the tools menu.

On Team and Enterprise plans, an organization owner adds the connector once under Organization settings > Connectors > Add > Custom (choose Web if asked for a type). Each team member then finds it under Customize > Connectors and clicks Connect to sign in with their own ImmyBot account — so the AI only ever has that person’s ImmyBot permissions.

Claude Code

Uses a personal access token. Run this once per machine (Claude Code stores the connection in its own local configuration):

claude mcp add --transport http immybot <your-server-address>/mcp --header "Authorization: Bearer <your-token>"

Then, inside Claude Code, type /mcp to confirm the immybot server shows as connected. By default this registers the server for the current project only; add --scope user to make it available in every project.

ChatGPT and Codex

Codex CLI uses a personal access token. Add this to ~/.codex/config.toml, putting the token in an environment variable named IMMYBOT_TOKEN rather than writing it into the file:

[mcp_servers.immybot]
url = "https://yourinstance.immy.bot/mcp"
bearer_token_env_var = "IMMYBOT_TOKEN"

Restart Codex and ask it what ImmyBot tools it has to confirm the connection.

ChatGPT uses ImmyBot sign-in. Custom MCP connectors in ChatGPT require Developer Mode, which isn’t available on the free plan, and on Team, Enterprise, and Edu workspaces an admin must allow it first. In ChatGPT’s settings, find the connectors/apps section (OpenAI has renamed this area more than once), turn on Developer Mode under its advanced settings, then create a new connector with your connector URL and OAuth as the authentication method. ChatGPT’s connector dialog doesn’t accept a personal access token.

Cursor

Uses a personal access token. Add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json inside one project:

{
  "mcpServers": {
    "immybot": {
      "url": "https://yourinstance.immy.bot/mcp",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Open Cursor Settings > MCP and confirm immybot shows a green status and lists its tools.

Visual Studio Code with GitHub Copilot

Uses a personal access token. Add this to .vscode/mcp.json in your workspace. The inputs block makes VS Code prompt you for the token and store it securely, so the token never lives in the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "immybot-token",
      "description": "ImmyBot personal access token",
      "password": true
    }
  ],
  "servers": {
    "immybot": {
      "type": "http",
      "url": "https://yourinstance.immy.bot/mcp",
      "headers": {
        "Authorization": "Bearer ${input:immybot-token}"
      }
    }
  }
}

Click Start above the server entry, enter the token when prompted, then open Copilot Chat in Agent mode and check the tools list.

Other MCP clients

ImmyBot’s MCP server uses the current Streamable HTTP MCP transport, so any client that supports it can connect with the connector URL and either ImmyBot sign-in (OAuth) or a Authorization: Bearer <token> header — the same pattern shown above. ImmyBot doesn’t support the older SSE transport; clients that only speak stdio can generally use the mcp-remote bridge.

What you can do once connected

Once your AI tool is connected, just describe what you want in plain language. A few examples:

• “List all computers in the Acme tenant that haven’t checked in for more than 7 days.”
• “Show me which computers are missing this month’s Windows updates.”
• “Create a deployment that installs 7-Zip for the Contoso tenant.”
• “Run a script on computer XYZ that checks free disk space on C:.”

Behind the scenes, the AI is:

1. Using a search tool to find relevant PowerShell commands or API operations for what you asked.
2. Using a describe tool to look up exactly how to call them (parameters, required permissions, expected results).
3. Using an execute tool to actually run a short script against your instance — scoped to a specific computer or a specific tenant — and return the result.

Longer-running actions return a handle the AI can poll (get) or stop early (cancel). If a task spans multiple steps or targets, the AI may group them together with start_session / end_session so the related runs are easy to find afterward.

Available tools

Tool	What it does
search	Finds relevant PowerShell commands and API operations matching a query
describe	Shows full details for one command/operation — parameters, required permissions, expected output
execute	Runs a PowerShell script against a specific computer or tenant and returns the result (or a handle to check on it later)
get	Checks on or retrieves the output of a run that’s still in progress
cancel	Stops an in-progress run
start_session / end_session	Groups a set of related runs together under one label, useful for multi-step requests

There’s also one read-only resource (a static reference list of built-in PowerShell commands) that some non-AI MCP clients use directly instead of calling search.

Security and permissions

• Everything runs as you. A connected AI tool can only do what the signed-in user or token owner is already permitted to do in ImmyBot. If you don’t have the Run Arbitrary Scripts permission on a tenant, the AI can’t act on it either — you’ll see a permission error instead.
• Two permissions control who may connect at all. Use OAuth over MCP and Use personal access tokens over MCP live under the MCP section of a role and are MSP-level permissions. They only grant a way to sign in — what the AI can then do is governed by your ordinary permissions, above all Run Arbitrary Scripts.
• Full audit trail. Every run shows up in ImmyBot’s normal script-run history and audit log, attributed to the user whose sign-in or token was used — not to "MCP" or "AI" generically.
• Tokens aren’t scoped down. A personal access token grants the same access the user already has — there’s currently no way to create a token that’s limited to, say, read-only access or a single tenant. Don’t create tokens for shared or unattended use unless you’re comfortable with anything holding that token acting fully as you.
• Multi-tenant access follows your normal cross-tenant permissions — an MSP-level user’s connection can reach child tenants the same way that user already can in the ImmyBot UI; nothing about MCP loosens or tightens tenant boundaries.
• Turning MCP off is instant. Switching it off disconnects every AI client at once and hides the connector URL and tool list.

Limitations

• MCP is enabled or disabled for the whole instance — there’s no per-tenant on/off switch.
• Personal access tokens are all-or-nothing; there’s no scoped/read-only token type yet.
• Scripts run through MCP are subject to the same time and size limits as other automated scripts (long-running scripts are capped, and very large outputs are paginated rather than returned all at once).
• Sessions started with start_session automatically end after a period of inactivity, so don’t rely on a session staying open indefinitely between requests.
• Other MCP clients should work if they support the Streamable HTTP transport (or bridge through mcp-remote), but aren’t individually tested or documented here. Vendor connector UIs and config formats change often — re-check the per-client steps above when a client updates.

Troubleshooting

The connection fails / the client can’t reach the server. Confirm MCP is actually turned on (Step 1) and that you copied the full connector URL, including /mcp at the end.

You get a 403 error that mentions mcp:use_pat or mcp:use_oauth. Your role doesn’t include the MCP permission for the sign-in method you used — the error names the missing one. Ask an administrator to add it to your role under the MCP section. This is common for users whose role isn’t the built-in System Administrator (Legacy) role.

The AI says it doesn’t have permission to do something. This means the connected user doesn’t have the required permission (usually Run Arbitrary Scripts) on the tenant or computer being targeted — check with an ImmyBot administrator, or see Roles and Security.

The token stopped working. It has expired or been revoked. Create a new one and update your client — check the expiry column on Show more → MCP.

The ImmyBot sign-in card says "Not enabled". OAuth sign-in isn’t switched on for this instance. Use a personal access token, or contact ImmyBot support to enable ImmyBot sign-in.

Sign-in fails partway through in claude.ai or the Claude desktop app. If your organization uses Microsoft Entra Conditional Access, a policy may be blocking the ImmyBot MCP connector application. Ask your identity administrator to allow it, the same way ImmyBot’s own sign-in is allowed.

The AI does not see a tool you know exists, or shows tools that were removed. AI clients cache the tool list. Start a new chat, or disconnect and reconnect the ImmyBot connector, to pick up the current list.

A script the AI runs fails with a language-mode or "not allowed" error. This is the PowerShell sandbox blocking something (see the callout above) — the AI will typically retry with a different approach. If it keeps failing, ask for a simpler version of the request.

The AI complains the server "does not support SSE" or fails on a GET request. ImmyBot uses the current Streamable HTTP transport and answers GET requests with "method not allowed" by design. Make sure your client is up to date and configured for HTTP transport, not the older SSE transport.

I disabled MCP but a client still shows as configured. That’s expected — disabling MCP doesn’t remove your client’s saved configuration, it just makes calls fail until you re-enable it.

Related pages

• Roles and Security — understand the permissions referenced above
• Creating & Managing Tasks — how scripts and tasks work in ImmyBot generally
• ImmyBot API Documentation — the same REST API surface MCP tools call into, if you want to build something more custom