ghively/Hexnode-MCP

Hexnode MCP Server

A production-ready Model Context Protocol (MCP) server that provides comprehensive integration with Hexnode's device management REST API. This server enables AI assistants to interact with Hexnode MDM through a clean, safe, and well-validated interface.

Key Features

• Comprehensive Device Management - List, query, and manage devices across your Hexnode tenant
• Advanced Policy Operations - Create, update, and manage policies with expanded section support
• Safety-First Design - Destructive actions are disabled by default and require explicit enablement
• Robust Error Handling - Automatic retries for safe operations with exponential backoff
• Structured Logging - Secure logging with PII redaction to STDERR only
• Full TypeScript - Strict typing with Zod validation for all inputs
• Flexible Deployment - Supports local development, Docker, and systemd/launchd services

Documentation

• - High-level components and data flow
• - Complete tool reference with inputs/outputs
• - Development setup and testing workflow
• - Security model and authentication
• - Common issues and solutions
• - Example inputs for expanded policy operations
• - Endpoint reference mapping

Quick Start

1. Environment Setup

# Copy environment template
cp .env.example .env

# Edit .env with your Hexnode credentials:
# HEXNODE_BASE=https://your-tenant.hexnodemdm.com/api/v1
# HEXNODE_API_KEY=your-api-key-here
# ALLOW_DESTRUCTIVE=false  # Set to 'true' to enable write operations

2. Install and Build

npm ci                    # Install exact dependencies
npm run build            # Build TypeScript to dist/

3. Quick Verification

./lets go                # Helper script: loads .env, builds, validates endpoints

4. Development vs Production

# Development (watch mode)
npm run dev

# Production
npm start                # Runs built server from dist/

Claude Desktop Setup

To use this MCP server with Claude Desktop:

1. Install and Build

git clone <this-repository>
cd hexnode-mcp
npm ci && npm run build

2. Configure Environment

Create .env file with your Hexnode credentials:

HEXNODE_BASE=https://your-tenant.hexnodemdm.com/api/v1
HEXNODE_API_KEY=your-hexnode-api-key
ALLOW_DESTRUCTIVE=false

3. Add to Claude Desktop

Add to your Claude Desktop MCP configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "hexnode": {
      "command": "node",
      "args": ["/absolute/path/to/hexnode-mcp/dist/server.js"],
      "env": {
        "HEXNODE_BASE": "https://your-tenant.hexnodemdm.com/api/v1",
        "HEXNODE_API_KEY": "your-api-key",
        "ALLOW_DESTRUCTIVE": "false"
      }
    }
  }
}

4. Restart Claude Desktop

Restart Claude Desktop to load the new MCP server. The Hexnode tools will be available in your conversations.

Prerequisites

• Node.js 20+ - Required for running the server
• Hexnode Account - Active Hexnode MDM tenant with API access
• API Credentials:
  • HEXNODE_BASE: Your tenant's API base URL (e.g., https://tenant.hexnodemdm.com/api/v1)
  • HEXNODE_API_KEY: Valid API key from your Hexnode admin panel
• Optional: Docker for containerized deployment

Architecture Overview

[AI Client] ⇄ STDIO ⇄ [MCP Server]
                         ├─ Input Validation (Zod schemas)
                         ├─ Tool Handlers (20+ tools)
                         ├─ HTTP Client (retry + auth)
                         ├─ Secure Logging (STDERR only)
                         └─ Hexnode REST API

Core Components:

• Tool Layer: 20+ specialized tools for device and policy management
• HTTP Layer: Automatic retries, authentication, error handling
• Safety Layer: Destructive operations guarded by ALLOW_DESTRUCTIVE flag
• Logging Layer: Structured logs with PII redaction to STDERR

Available Tools

Device Management (Safe)

• list_devices - List devices with filtering (platform, status, type, pagination)
• get_device - Get detailed device information by ID
• list_devices_by_policy - List devices assigned to a specific policy
• list_devices_by_user - List devices assigned to a specific user

Policy Management (Safe)

• list_policies - List all policies with pagination (auto-falls back between /policy/ and /policies/ depending on tenant)
• get_policy - Get basic policy information by ID (auto-falls back between /policy/{id}/ and /policies/{id}/)
• get_policy_expanded - Get policy with all section details; base and sections auto-try singular/plural variants

Generic API Access (Safe)

• hexnode_get - Safe GET requests to any Hexnode endpoint
• hexnode_probe - Probe endpoints for status and preview content

⚠️ Destructive Operations (Guarded)

Require ALLOW_DESTRUCTIVE=true

Device Actions:

• lock_device - Lock devices remotely with optional message and PIN
• mark_device_unenrolled - Mark devices as unenrolled
• delete_device - Permanently delete devices from Hexnode

Policy Operations:

• create_policy - Create new policies (uses singular /policy/)
• update_policy - Update existing policies (uses singular /policy/{id}/)
• create_policy_expanded - Create policy with detailed section configuration
• update_policy_expanded - Update policy sections (restrictions, VPN, etc.)
• assign_policy - Assign policies to devices/users/groups
• unassign_policy - Remove policy assignments
• policy_force_update - Force policy refresh on targets

Generic Write Operations:

• hexnode_post - POST requests with payload wrapping options
• hexnode_put - PUT requests for resource updates
• hexnode_delete - DELETE requests for resource removal

Endpoint Validation & Probing (Safe)

Test Hexnode connectivity and permissions (handles rate limiting with Retry-After and pacing):

PROBE_DELAY_MS=1500 npm run validate:endpoints

Optional test IDs (set as environment variables):

DEVICE_ID=123 USER_ID=456 POLICY_ID=789 npm run validate:endpoints

Output includes endpoint status, response previews, and available HTTP methods.

Policy sections (OPTIONS-only)

Inventory write-capable policy section endpoints without using GET:

PROBE_DELAY_MS=2000 OPTIONS_ONLY=true npm run probe:policy:sections

Generate per-tenant paths/methods

Produce a path_map/method_map suited to your tenant’s endpoints (kept local under configs/ which is git‑ignored):

OUTPUT_FILE=configs/tenants/<tenant>.paths.json PROBE_DELAY_MS=1500 npm run suggest:policy:paths

Dump policy + sections (GET, slower)

PROBE_DELAY_MS=1500 POLICY_ID=<id> npm run dump:policy

This respects Retry-After but can take longer under throttling. Consider the OPTIONS-only probe first.

Security Model

Authentication

• API Key: Sent as Authorization header on every request
• Transport: Secure STDIO communication (no network exposure)
• Credentials: Never logged or exposed in output

Safety Controls

• Destructive Protection: Write operations disabled by default
• Explicit Enable: Set ALLOW_DESTRUCTIVE=true to enable write operations
• Operation Scope: Granular control over device actions and policy changes
• Input Validation: All inputs validated with Zod schemas

Logging

• Target: All logs written to STDERR (STDOUT reserved for MCP protocol)
• Content: Only logs method, path, status, duration - never credentials or PII
• Format: Structured JSON for easy parsing and monitoring
• Redaction: Automatic redaction of sensitive headers and query parameters

Environment Variables

Optional Test IDs (for endpoint validation)

Development

Local Development

# Install dependencies
npm ci

# Start in watch mode
npm run dev

# Run tests
npm test

# Validate your Hexnode connection
npm run validate:endpoints

Production Deployment

# Build for production
npm run build

# Run built server
npm start

Testing

• Framework: Vitest with Node.js environment
• Location: tests/**/*.test.ts
• Mocking: Network I/O mocked (never hits real Hexnode in tests)
• Run: npm test or npx vitest

Policy Configuration

Expanded Policy Tools

The server provides enhanced policy tools that work with individual policy sections:

Supported Sections:

• restrictions - Device restrictions and limitations
• authentication - Authentication policies
• login_window - macOS login window settings
• setup_assistant - Device setup configuration
• power_management - Power and sleep settings
• deployment_scripts - Automated deployment scripts
• app_store_controls - App Store access controls
• media_management - Media and content controls
• password - Password policies
• firewall - Firewall configurations
• vpn - VPN connection settings
• wifi - WiFi network configurations
• filevault - Disk encryption settings
• Mac_OS_Update - macOS update policies

Customization

• Path Mapping: Override default section endpoints with path_map
• HTTP Methods: Customize HTTP verbs with method_map (PUT/POST/PATCH)
• Error Handling: Missing/forbidden sections return {"skipped": true}

Example

// Update policy with custom path mapping
{
  "policy_id": 123,
  "sections": {
    "restrictions": { /* restriction settings */ },
    "vpn": { /* VPN configuration */ }
  },
  "path_map": {
    "restrictions": "/policies/{id}/custom-restrictions/"
  },
  "method_map": {
    "vpn": "PATCH"
  }
}

Deployment Options

Docker

# Build image
docker build -t hexnode-mcp:0.1.0 .

# Run container
docker run --rm -i \
  -e HEXNODE_BASE="https://your-tenant.hexnodemdm.com/api/v1" \
  -e HEXNODE_API_KEY="your-api-key" \
  -e ALLOW_DESTRUCTIVE="false" \
  hexnode-mcp:0.1.0

System Services

• Linux: systemd service examples in docs/DEPLOYMENT.md
• macOS: launchd plist examples in docs/DEPLOYMENT.md
• Windows: Windows Service configuration guidance

Security Best Practices

• Run as dedicated user with minimal privileges
• Use environment files or service environment blocks (never command line)
• Enable destructive operations only when necessary
• Monitor logs for suspicious activity
• Regularly rotate API keys

Usage Examples

Device Management

// List iOS devices with pagination
list_devices({
  "platform": "ios",
  "per_page": 10,
  "is_active": true
})

// Get specific device details
get_device({
  "device_id": 123
})

// Lock device with message (requires ALLOW_DESTRUCTIVE=true)
lock_device({
  "devices": [123],
  "message": "Device locked for security",
  "system_lock_pin": "123456"
})

Policy Operations

// List all policies
list_policies({
  "per_page": 20
})

// Get policy with all sections
get_policy_expanded({
  "policy_id": 456,
  "include": ["restrictions", "vpn", "wifi"],
  "merge": true
})

// Create comprehensive policy (requires ALLOW_DESTRUCTIVE=true)
create_policy_expanded({
  "policy": {
    "name": "Corporate Security Policy",
    "description": "Standard corporate device policy"
  },
  "sections": {
    "restrictions": {
      "allow_app_installation": false,
      "allow_camera": true
    },
    "wifi": {
      "ssid": "CorporateWiFi",
      "security_type": "WPA2"
    }
  }
})

Generic API Access

// Safe exploration
hexnode_probe({
  "path": "/users/",
  "max_bytes": 500
})

// Custom GET request
hexnode_get({
  "path": "/devices/",
  "query": {
    "platform": "android",
    "enrollment_status": "active"
  }
})

Error Handling & Reliability

Automatic Retries

• Scope: Only safe GET operations
• Triggers: HTTP 429, 502, 503, 504 status codes
• Strategy: Exponential backoff with jitter (max 3 attempts)
• Timing: 300ms base delay, 2x factor, random jitter

Error Responses

• HTTP Errors: Structured error with status code and response excerpt
• Guard Messages: Clear text when destructive operations are disabled
• Validation Errors: Detailed Zod validation failures
• Network Errors: Connection and timeout error details

Logging Format

[hexnode-mcp tool=list_devices method=GET path=/devices/ status=200 ms=245]

Performance & Limitations

Rate Limiting

• Client Responsibility: Respect Hexnode API rate limits
• No Built-in Throttling: Server does not implement rate limiting
• Recommendation: Space out requests, especially for batch operations
• Monitoring: Watch for 429 responses in logs

Pagination

• Manual Pagination: Use page and per_page parameters
• No Auto-pagination: Server returns single page responses
• Best Practice: Start with reasonable per_page values (10-50)

Resource Usage

• Memory: Minimal - processes one request at a time
• Network: Efficient with connection reuse and retries
• CPU: Low overhead with TypeScript compilation cached

Troubleshooting

Common Issues

Environment Variables Not Loaded

# Check if .env is being loaded
./lets go

# Or manually verify
echo $HEXNODE_BASE
echo $HEXNODE_API_KEY

401/403 Authentication Errors

• Verify API key is valid and active
• Check API key permissions in Hexnode admin panel
• Ensure HEXNODE_BASE URL is correct (include /api/v1)

Destructive Actions Blocked

# Enable write operations
echo 'ALLOW_DESTRUCTIVE=true' >> .env

# Restart the server
npm start

Network/Timeout Issues

• Check Hexnode service status
• Verify network connectivity
• Review firewall settings for outbound HTTPS
• Monitor for 429 rate limit responses

Advanced Configuration

Custom Endpoint Paths

Some Hexnode tenants may use different endpoint patterns:

// Override default paths
list_devices_by_policy({
  "policy_id": 123,
  "path_override": "/custom/policies/123/assigned-devices/"
})

Expanded Policy Customization

// Custom section paths and HTTP methods
update_policy_expanded({
  "policy_id": 123,
  "sections": {
    "custom_section": { /* config */ }
  },
  "path_map": {
    "custom_section": "/policies/{id}/my-custom-endpoint/"
  },
  "method_map": {
    "custom_section": "PATCH"
  }
})

Debugging

Enable verbose logging by monitoring STDERR output:

# Development with log monitoring
npm run dev 2>&1 | grep hexnode-mcp

# Production with log file
npm start 2>hexnode.log

Contributing

See for development guidelines and for repository structure.

Development Workflow

1. Fork and clone the repository
2. Install dependencies: npm ci
3. Create feature branch: git checkout -b feature-name
4. Make changes with tests: npm test
5. Build and validate: npm run build && npm run validate:endpoints
6. Submit pull request with clear description

License & Disclaimer

Disclaimer: This project is not affiliated with or endorsed by Hexnode. Hexnode and related product names are trademarks of their respective owners. Use this software at your own risk and in accordance with your Hexnode API terms and policies. 404 on policy endpoints

• This server is configured to use singular /policy/ paths exclusively for policy resources on this tenant.
• For manual checks, probe with hexnode_probe_advanced on /policy/ paths.

Directory (Safe)

• list_users - List users with pagination
• get_user - Get a user by ID
• list_usergroups - List user groups with pagination
• get_usergroup - Get a user group by ID
• list_devicegroups - List device groups with pagination
• get_devicegroup - Get a device group by ID
• list_appgroups - List app groups with pagination
• get_appgroup - Get an app group by ID

Directory (Guarded)

Require ALLOW_DESTRUCTIVE=true:

• Users: create_user, update_user, delete_user_rest
• User Groups: create_usergroup, update_usergroup, delete_usergroup, modify_usergroup_users
• Device Groups: create_devicegroup, update_devicegroup, delete_devicegroup, modify_devicegroup_devices
• App Groups: create_appgroup, update_appgroup, delete_appgroup, modify_appgroup_apps
• Apps: create_app, update_app, delete_app
• App Catalogs: create_appcatalog, update_appcatalog, delete_appcatalog, modify_appcatalog_apps