Desktop Management MCP Server

Standalone Model Context Protocol (MCP) servers for JAMF Pro and Microsoft Intune. AI assistants (Claude Code, Gemini CLI, OpenCode, etc.) connect over HTTP and call device-management tools.

Architecture

MCP Client  ──HTTP──▶  jamf-server (port 3001)  ──▶  JAMF Pro REST API
MCP Client  ──HTTP──▶  intune-server (port 3002) ──▶  Microsoft Graph API

Each server is a stateless Express app using @modelcontextprotocol/sdk. Every POST to /mcp creates a fresh StreamableHTTPServerTransport. Secrets are injected at runtime by Bitwarden Secrets Manager — no credentials are stored in the repo.

Related MCP server: domotz-mcp

Prerequisites

• Node.js 24+

• BWS CLI (bws in PATH)

• A Bitwarden Secrets Manager project with the secrets listed in bws-secrets.map

• JAMF Pro API client credentials (OAuth2)

• Azure AD app registration with Microsoft Graph permissions (for Intune)

• (Optional) A Microsoft Entra ID resource app registration with App Roles, if you want per-user OAuth instead of the shared static token — see Authentication

Quick Start

# Install dependencies and build
npm install && npm run build

# Set your BWS machine account access token
export BWS_ACCESS_TOKEN="<your-token>"

# Start whichever server(s) you need
./start-jamf.sh    # JAMF MCP on http://localhost:3001/mcp
./start-intune.sh  # Intune MCP on http://localhost:3002/mcp

See bws-secrets.map for the secret names to create in your BWS project.

Authentication

/mcp on both servers requires Authorization: Bearer <token> (not required on /health). Requests without a valid token get 401; if a server has no auth mechanism configured at all, every /mcp request fails closed with 503 rather than being let through unauthenticated. Two independent modes are accepted on the same endpoint:

1. Static bearer token — JAMF_MCP_AUTH_TOKEN / INTUNE_MCP_AUTH_TOKEN (comma-separated to allow rotating without downtime). This is the only mechanism available to non-interactive automation (scripts, n8n), and grants that server's full tool set — every tool below, including the destructive ones. Treat this token as equivalent to full admin access to the corresponding backend.

2. Entra ID OAuth (ENTRA_OAUTH_ENABLED=true) — a JWT issued by Microsoft Entra ID, verified against Entra's JWKS. Tool visibility is driven by the token's roles claim (Jamf.Read, Jamf.Write, Intune.Read — see src/utils/roles.ts): a tool a caller's role doesn't grant is never registered on that request's server instance, so it's not just hidden, it's uncallable. This lets real staff authenticate as themselves instead of sharing one all-or-nothing token.

jamf_send_mdm_command is flagged destructiveHint: true and supports EraseDevice (irreversible) among other commands; it and the other nine write/mutating JAMF tools (computer/prestage/inventory-preload updates, MDM flush, plus the script/package/smart-group/policy create-and-update tools) are gated behind the Jamf.Write role under Entra auth (or the static token, which grants both read and write). Anyone holding a valid JAMF_MCP_AUTH_TOKEN can call all of them — the token itself is the access boundary for the automation path.

In production (podman02), network exposure is layered on top of this: internal-DNS-only hostnames, plus a Caddy IP allowlist. /mcp's bearer-token requirement is the one layer that's actual authentication rather than network-level exposure control, and the one that still holds if the other two are ever misconfigured — see CLAUDE.md for the full deployment/defense-in-depth writeup.

Setting up Entra ID OAuth (optional)

1. Register one Entra app to act as the OAuth resource server, e.g. "Desktop Management MCP". Give it an Application ID URI using a verified-domain form (a bare custom string like api://desktop-mgmt-mcp is rejected by tenants that require a verified domain — Colgate's does; use api://<verified-domain>/desktop-mgmt-mcp instead), a delegated access_as_user scope, and App Roles matching src/utils/roles.ts (Jamf.Read, Jamf.Write, Intune.Read). Turn on "User assignment required" and assign roles to users or groups via Enterprise Applications.

2. Also register each server's own literal MCP URL (e.g. https://jamf-mcp.colgate.edu/mcp) as an additional identifierUris entry on that same app. MCP-spec clients (OpenCode, mcp-remote) send an RFC 8707 resource parameter set to that literal URL; if it doesn't resolve to the same app as the requested scope, Entra rejects the request with AADSTS9010010. One resource app can have multiple identifier URIs, so this doesn't require separate apps per server.

3. Register one small public/native client app (PKCE, no secret) for interactive clients, pre-authorized for the resource app's access_as_user scope so users skip the consent screen.

4. Decode a real issued token before assuming the audience format: Entra sometimes audiences tokens to the resource app's GUID app ID rather than its Application ID URI, specifically when a client sends the resource parameter — confirmed live, not something the requestedAccessTokenVersion: 2 setting prevents. createEntraVerifier accepts both forms via the optional ENTRA_RESOURCE_APP_ID env var.

See CLAUDE.md's Authentication and roles section for the code-level details, and the per-client config below for what actually works today.

Environment Variables

Injected by bws run from your BWS project (see bws-secrets.map):

JAMF Pro:

• JAMF_URL — e.g. https://yourorg.jamfcloud.com

• JAMF_CLIENT_ID, JAMF_CLIENT_SECRET

• JAMF_MCP_AUTH_TOKEN — bearer token(s) MCP clients must present (comma-separated to allow rotation)

• JAMF_MCP_PUBLIC_URL — this server's externally-visible origin, e.g. https://jamf-mcp.colgate.edu (required only when ENTRA_OAUTH_ENABLED=true, used to build RFC 9728 resource metadata)

• JAMF_PACKAGE_UPLOAD_DIR — directory jamf_upload_package may read files from on this server's own filesystem. Required for that tool; it refuses every call if unset.

Microsoft Intune:

• AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET — Graph app-only client credentials for device data; unrelated to the Entra auth vars below

• INTUNE_MCP_AUTH_TOKEN — bearer token(s) MCP clients must present (comma-separated to allow rotation)

• INTUNE_MCP_PUBLIC_URL — this server's externally-visible origin, e.g. https://intune-mcp.colgate.edu (required only when ENTRA_OAUTH_ENABLED=true)

Entra ID auth (optional; shared by both servers — see CLAUDE.md for the caveat that a single shared deployment env file means both servers currently enable/disable together despite the per-service naming):

• ENTRA_OAUTH_ENABLED — "true" to accept Entra-issued bearer tokens on /mcp in addition to the static token

• ENTRA_TENANT_ID — Entra tenant GUID (deliberately separate from AZURE_TENANT_ID above — different app registration, different purpose, don't reuse one BWS secret for both)

• ENTRA_RESOURCE_APP_ID_URI — Application ID URI of the resource app, e.g. api://colgate.edu/desktop-mgmt-mcp

• ENTRA_RESOURCE_APP_ID — GUID app ID of the same resource app; accepted as an alternate valid aud value (see Authentication above)

Azure AD Graph Permissions

The Intune app registration needs these Application permissions (with admin consent):

• Device.Read.All

• DeviceManagementManagedDevices.Read.All

• DeviceManagementApps.Read.All

• DeviceManagementConfiguration.Read.All

• Group.Read.All

• User.Read.All

Client Configuration

Point clients at http://localhost:<port>/mcp for a locally-running server, or at the https:// hostname below when talking to the podman02 deployment (Caddy terminates TLS and reverse-proxies to the container over plain HTTP — the servers themselves never speak TLS directly).

The podman02 hostnames resolve only inside Colgate's network (internal DNS locale) — see IAC/ansible-servers/linux/apps/desktop-management-mcp.yml. Both deployments require a bearer token on /mcp (see Authentication above); several JAMF tools are destructive, so treat the token — not just the URL — as sensitive.

Claude Code — static token (works today)

{
  "mcpServers": {
    "jamf": {
      "type": "http",
      "url": "https://jamf-mcp.colgate.edu/mcp",
      "headers": { "Authorization": "Bearer <JAMF_MCP_AUTH_TOKEN value>" }
    },
    "intune": {
      "type": "http",
      "url": "https://intune-mcp.colgate.edu/mcp",
      "headers": { "Authorization": "Bearer <INTUNE_MCP_AUTH_TOKEN value>" }
    }
  }
}

Or via the CLI: claude mcp add --transport http jamf https://jamf-mcp.colgate.edu/mcp --header "Authorization: Bearer <token>".

Claude Code — Entra ID OAuth (per-user identity)

Claude Code's native HTTP-transport OAuth (claude mcp add --transport http ... --client-id ...) does not send a scope parameter and fails against Entra with AADSTS900144 — confirmed live, not a hypothetical. Use the mcp-remote bridge instead, which supports an explicit scope:

npm install -g mcp-remote   # or use npx, at the cost of a re-fetch each launch

{
  "type": "stdio",
  "command": "mcp-remote",
  "args": [
    "https://jamf-mcp.colgate.edu/mcp",
    "3334",
    "--static-oauth-client-info",
    "{\"client_id\":\"<public-client-id>\"}",
    "--static-oauth-client-metadata",
    "{\"scope\":\"openid profile offline_access <resource-app-id-uri>/access_as_user\"}"
  ]
}

Add with claude mcp add-json jamf-remote -s user '<json above>', then trigger the OAuth flow with claude mcp get jamf-remote (or just start using its tools — first use triggers auth). Pin an explicit port per server (mcp-remote otherwise derives one from a hash of the server URL, which works but is less predictable) and register the exact resulting redirect URI — http://localhost:<port>/oauth/callback, note localhost not 127.0.0.1, and a different path than OpenCode uses below — on the Entra public client.

Gemini CLI (~/.gemini/settings.json)

{
  "mcpServers": {
    "jamf": { "httpUrl": "https://jamf-mcp.colgate.edu/mcp", "headers": { "Authorization": "Bearer <JAMF_MCP_AUTH_TOKEN value>" } },
    "intune": { "httpUrl": "https://intune-mcp.colgate.edu/mcp", "headers": { "Authorization": "Bearer <INTUNE_MCP_AUTH_TOKEN value>" } }
  }
}

OpenCode (~/.config/opencode/opencode.json)

Static token:

{
  "mcp": {
    "jamf": {
      "type": "remote",
      "url": "https://jamf-mcp.colgate.edu/mcp",
      "enabled": true,
      "headers": { "Authorization": "Bearer <JAMF_MCP_AUTH_TOKEN value>" }
    }
  }
}

Entra ID OAuth (confirmed working live end-to-end — opencode mcp auth jamf drives a normal browser PKCE flow):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jamf": {
      "type": "remote",
      "url": "https://jamf-mcp.colgate.edu/mcp",
      "enabled": true,
      "oauth": {
        "clientId": "<public-client-id>",
        "scope": "openid profile offline_access <resource-app-id-uri>/access_as_user"
      }
    }
  }
}

OpenCode's OAuth callback listens on a fixed http://127.0.0.1:19876/mcp/oauth/callback (not currently configurable) — register that exact redirect URI on the Entra public client. If OpenCode runs on a different machine than your browser (e.g. a remote dev VM), the redirect won't reach the listener; tunnel the port with ssh -L 19876:localhost:19876 <host> before running opencode mcp auth.

Swap in the http://localhost:<port>/mcp URLs from the table above for local development.

MCP Tools Reference

JAMF Pro Tools

jamf_send_mdm_command is the one tool flagged destructiveHint: true (supports EraseDevice, irreversible on Apple Silicon without the erasure passcode). It and the other write tools below require the Jamf.Write role under Entra auth. jamf_create_script/jamf_upload_package/jamf_create_smart_group are upserts by name (re-running updates the existing object in place); jamf_create_policy always creates a new policy; jamf_update_policy handles enable/disable + scope widening for an existing one. See CLAUDE.md for the Classic-API-requires-XML detail and the known Delete-permission gap (Scripts/Policies/Smart Groups can be created/updated but not deleted by this API client — package deletion does work).

Microsoft Intune Tools

Running Tests

export BWS_ACCESS_TOKEN="<your-token>"
bws run --access-token "$BWS_ACCESS_TOKEN" -- \
  TEST_COMPUTER_NAME="<name>" \
  TEST_COMPUTER_SERIAL="<serial>" \
  TEST_USER_EMAIL="<email>" \
  npm test

Add JAMF_TEST_WRITE=1 to enable destructive write tests (MDM commands, inventory updates) against live JAMF Pro. The script/smart-group/policy upsert tests additionally need a pre-existing, manually-created fixture object named via TEST_SCRIPT_NAME/TEST_SMART_GROUP_NAME/TEST_POLICY_NAME (each optional — the test skips if unset or if no object with that name exists yet, since this API client can create/update but not delete those object types). The package upsert test is fully self-cleaning via TEST_PACKAGE_PATH (also optional) pointing at a small .pkg/.dmg inside JAMF_PACKAGE_UPLOAD_DIR.

npm run test:unit runs just the auth/roles unit tests (test/auth.test.ts) — no live credentials or network access needed, since they exercise requireMcpAuth's fallback/fail-closed logic and the roles.ts helpers against fakes.

Project Structure

├── src/
│   ├── mcp/
│   │   ├── jamf-server.ts      # JAMF standalone MCP server (port 3001)
│   │   └── intune-server.ts    # Intune standalone MCP server (port 3002)
│   ├── jamf/
│   │   └── jamf-api.ts         # JAMF Pro REST + Classic API client
│   ├── intune/
│   │   └── graph-api.ts        # Microsoft Graph / Intune client
│   └── utils/
│       ├── auth.ts             # requireMcpAuth: static-token / Entra JWT dual-mode middleware
│       ├── entra-jwt.ts        # Entra JWT verification (jose) + RFC 9728 resource metadata
│       ├── roles.ts            # Entra App Role constants and role-checking helpers
│       └── logger.ts           # Output formatting helpers
├── test/
│   ├── jamf-api.test.ts        # Live integration tests against real JAMF Pro
│   └── auth.test.ts            # Auth/roles unit tests — no live credentials needed
├── start-jamf.sh               # BWS-wrapped launcher for JAMF server
├── start-intune.sh             # BWS-wrapped launcher for Intune server
└── bws-secrets.map             # Required BWS secret names and descriptions

Additional Resources

• MCP Specification

• JAMF Pro API Docs

• Microsoft Graph API Docs

• Bitwarden Secrets Manager

• MCP Authorization spec (RFC 8707 resource indicators, RFC 9728 protected resource metadata)