> For the complete documentation index, see [llms.txt](https://docs.autopilotmonitor.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.autopilotmonitor.com/integrations/ai-integration-mcp.md). # AI Integration (MCP) Query your enrollment data in natural language — connect Claude or any MCP client to the Autopilot Monitor MCP server. Autopilot Monitor exposes a **Model Context Protocol (MCP)** server that lets AI assistants query enrollment data conversationally: *"show me all failed enrollments from the last 24 hours"*, *"why did session X fail?"*, *"which devices are affected by CVE-2024-30078?"*. Connect Claude Desktop, VS Code with Claude, or any MCP client supporting Streamable HTTP. ## How it works ``` AI client → MCP server → Backend API → Your data ``` Your existing sign-in token is forwarded with every request — the MCP server stores no credentials, and all data access is scoped to your tenant exactly like in the portal. ## Prerequisites 1. **A role in your organization's tenant** — MCP access follows your portal role: an account with a role (Admin, Operator or Viewer) can connect, an account without one cannot, and individual accounts can be blocked. On request, MCP can also be switched off for your whole organization; every connection attempt then shows the recorded reason, while portal and API access stay unchanged. Tenant admins can see usage under **Configuration → Reporting → MCP Usage**. 2. **An MCP-compatible client** — Claude Desktop, VS Code with the Claude extension, or anything speaking Streamable HTTP with OAuth. Unattended automation connects with its own application identity instead — see [Service principals and automation](#service-principals-and-automation). ## Client setup **Server URL:** ``` https://mcp.autopilotmonitor.com/mcp ``` * **Claude Desktop:** Settings → MCP Servers → Add, enter the URL. OAuth authentication runs automatically in the browser. * **VS Code (Claude extension):** add to `.vscode/mcp.json` or user settings: ```json { "servers": { "autopilot-monitor": { "type": "http", "url": "https://mcp.autopilotmonitor.com/mcp" } } } ``` ### Optional: readable (indented) results Tool results are compact JSON by default because indentation costs your assistant tokens on every call. If you read raw results yourself (for example in an IDE), send the request header `X-MCP-Pretty: 1` and the server returns indented JSON for that client only. * **VS Code (Claude extension):** add a `headers` object to the server entry: ```json { "servers": { "autopilot-monitor": { "type": "http", "url": "https://mcp.autopilotmonitor.com/mcp", "headers": { "X-MCP-Pretty": "1" } } } } ``` * **Claude Code (CLI):** pass the header when adding the server: ``` claude mcp add --transport http autopilot-monitor https://mcp.autopilotmonitor.com/mcp --header "X-MCP-Pretty: 1" ``` Remove the header again when you no longer read raw results — every indented response costs roughly 15–45 % more tokens. **Verify:** ask your assistant *"List all available tools from Autopilot Monitor"* — you should see 20+ tools. If authentication fails, your MCP access probably isn't enabled yet. ## Protocol support The server implements the **current MCP specification (revision 2026-07-28)** — the stateless Streamable HTTP transport with `server/discover`, cache hints on tool and resource listings, and header-based request routing — and stays compatible with clients that still use the previous (2025) handshake. You do not have to configure anything: a client picks the newest revision it understands, and the tools, resources and instructions it sees are identical on either path. Authentication follows the specification's OAuth 2.1 profile: PKCE (S256) is mandatory, the authorization response carries the RFC 9207 issuer so clients can detect mix-up attacks, and clients register either through a **Client ID Metadata Document** (the client identifies itself with an HTTPS URL that serves its metadata — the mechanism the current specification recommends) or, for older clients, through Dynamic Client Registration. Redirect targets are always checked against a fixed allowlist of AI-vendor callback URLs plus loopback, whichever registration mechanism a client uses. ## Signing in — which account goes where Connecting the MCP server involves **two sign-ins**, and they are often two *different* accounts: the account of your AI subscription (e.g. your personal Claude account) and the work account you use for Autopilot Monitor (often a separate admin account). This is the most common source of confusion during setup. ```mermaid flowchart TD A(["You click Connect on the Autopilot Monitor MCP in your AI client"]) A --> B["Step 1 — Microsoft sign-in opens in your browser

Sign in with your Autopilot Monitor account
e.g. adm.luke@contoso.com"] B --> C["Step 2 — Browser returns to your AI vendor's site
e.g. claude.ai

The browser must already be signed in there with your
AI account — the same one as in the app, e.g. luke@contoso.com"] C --> D(["✅ Done — the assistant now queries Autopilot Monitor
with your work identity"]) ``` {% hint style="info" %} **The one rule to remember:** your **default browser** needs **two sign-ins** — at your AI vendor (e.g. claude.ai) with your **AI account** (the same one used in the app), and at the Microsoft sign-in with your **Autopilot Monitor account**. This only matters when those are two different accounts — if you use one and the same account for both, you won't notice any of this. {% endhint %} If the connect hangs or fails after the Microsoft sign-in succeeded, it is almost always the first half that's missing: the browser is not (or with the wrong account) signed in at your AI vendor's site. Typical causes are multiple browser profiles, or being signed in to the desktop app only but not in the browser. Sign in to the vendor site in your default browser first, then retry the connect. ## Available tools | Category | Tools | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Search & Discovery** | `search_sessions` (by status, device properties, serial, model, OS, location…) · `search_sessions_by_event` · `search_sessions_by_cve` · `search_events` (hybrid keyword + semantic — finds "machine restarted unexpectedly" without literal word overlap) · `search_knowledge` (semantic search over your rules and IME patterns; an error code in the query also returns its catalog entry) · `lookup_error_code` (explains one Windows, MSI, Windows Update, AppX or Intune error code by hex, decimal, symbol or IME enforcement state) · `search_docs` (semantic search over this documentation) | | **Session Analysis** | `get_session_summary` (the best starting point: overview, observation coverage with a `gaps` list of what the agent could not see, key events, rule analysis, annotations, stats) · `get_session` · `get_session_events` | | **Metrics & Observability** | `get_metrics` · `get_app_install_metrics` (incl. Delivery Optimization rollup) · `get_time_attribution` (where enrollment time goes — one session or the fleet) · `get_device_history` (a device's enrollment attempts, or the fleet's first-time-right rate) · `get_geographic_metrics` / `get_geographic_sessions` · `get_vulnerability_summary` · `get_rule_stats` (incl. active rule regressions) · `get_ime_version_history` · `get_usage_metrics` | | **Inventory & Audit** | `get_software_inventory` · `get_audit_logs` | | **Raw Data** | `query_raw_events` · `query_raw_sessions` · `get_resource` (discovery catalogs) | Two **discovery resources** help the assistant use the right vocabulary: `event_types` (every event type string, by category) and `device_properties` (dot-notation property keys like `tpm_status.specVersion` or `hardware_spec.ramTotalGB`). `search_docs` searches this documentation site, so the assistant can answer product questions — setup, roles, settings, notifications, security and privacy — and cite the page it used. It is a separate corpus from `search_knowledge`: ask *"how does X work?"* and it answers from the docs; ask *"why did this enrollment fail?"* and it reaches for your rules and session data instead. ## Example prompts * *"Show me all failed enrollments from the last 24 hours"* * *"Summarize session abc-123 and suggest fixes"* * *"Which apps cause the most timeouts during enrollment?"* * *"Compare enrollment performance between Germany and the US"* * *"Find enrollments with BitLocker issues"* * *"Which devices are affected by CVE-2024-30078?"* * *"How has the failure rate changed this week?"* * *"Where does enrollment time go in our user-driven enrollments, and which blocking app costs the most?"* * *"Which devices needed more than one attempt this month, and what failed the first time?"* * *"How do I roll the agent out with Intune?"* (answered from this documentation) The assistant picks the right tools and chains them — e.g. finding a session by device name first, then pulling its event timeline. ## Service principals and automation A scheduled report, a pipeline or an agent that runs without a person signed in connects with its **own application identity** rather than a user's. It is granted like a team member and is always read-only. 1. **Register the application in your Entra tenant** (or use one you already have — a federated credential, a certificate or a client secret all work; the platform only sees the resulting token). 2. **Grant it the Autopilot Monitor application permission.** On the application's **API permissions** page choose *APIs my organization uses* → **Autopilot Monitor** → *Application permissions* → `access_as_application`, then **Grant admin consent** for your tenant. Without this consent the token is refused before any role check. 3. **Add it as a member.** Under **Settings → Access Management** switch the add form to **Service principal**, enter the application (client) ID and add it. Service principals always hold the **Viewer** role; the role selector is fixed. To let it read tenants you manage as an MSP, assign it under **Settings → Tenant → Delegated Access** like any other member. 4. **Obtain a token and call the server.** Request a client-credentials token for `api://886ab5e2-6144-442c-80cc-9b28e0667731/.default` from your tenant's Entra endpoint and send it as `Authorization: Bearer …` to `https://mcp.autopilotmonitor.com/mcp` (Streamable HTTP). There is no OAuth sign-in and no browser step; the token typically lasts about an hour, after which the application requests a new one. Its calls count against your organization's MCP budget like a person's and appear on the **MCP Usage** page marked **App**; disabling or removing the member blocks it. A service principal can never change configuration, annotate sessions or trigger device actions, whatever its Entra permissions say. ## Rate limits and usage plans Requests are rate-limited to **60 per minute per user** (sliding window). Exceeding it returns HTTP 429 with `retryAfterSeconds`; clients typically retry automatically. Overall MCP usage is additionally **tied to your tenant's usage plan**, with two budgets: a daily and monthly quota **per account**, and a daily and monthly quota **for your whole organization** that every member's requests count against — adding accounts does not add budget. When either is exhausted, the assistant receives a message naming which budget it was and when it resets. Tenant admins can track consumption against both budgets under **Configuration → Reporting → MCP Usage**, including a breakdown of the organization budget by account. **Delegated (MSP) administrators:** a request into a tenant you manage counts against **that tenant's** organization budget and follows **its** plan — a Community customer is read with Community windows even from a Pro tenant. Your own per-account budget still comes from your home tenant. When a managed tenant's budget is exhausted, the assistant is told which tenant it was, and your other managed tenants stay available; the `get_fleet_overview` tool, which gives a bounded overview across all your managed tenants, skips exhausted tenants and lists them instead of failing. The customer's tenant admins see your requests on their MCP Usage page, marked as delegated. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.autopilotmonitor.com/integrations/ai-integration-mcp.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.