Master cPanel AI Assistants: Step‑by‑Step MCP Guide

cPanel & WHM now offer AI Assistants that help administrators automate routine tasks, generate configuration snippets, and troubleshoot issues. To keep these helpers secure, cPanel uses the Model Context Protocol (MCP) – a permission framework that defines which AI models can access which parts of the server. This guide walks you through the complete lifecycle of managing AI Assistants and MCP permissions on a typical cPanel/WHM installation.

1. Understanding AI Assistants and MCP

AI Assistants are plug‑in services that run inside the WHM environment. Each assistant is backed by a language model (for example, an OpenAI‑compatible model) and talks to WHM through the MCP API. MCP acts as a gatekeeper:

• Model IDs – unique identifiers for each registered AI model.
• Context Scopes – named groups of WHM functions (e.g., dns, mail, ssl) that an assistant may request.
• Permissions – explicit allow/deny rules that bind a Model ID to one or more Context Scopes.

Only assistants that have been granted permission can invoke the corresponding WHM APIs, preventing a mis‑configured or compromised model from altering critical services.

2. Prerequisites

Before you begin, ensure you have:

• Root SSH access to the server running cPanel/WHM.
• WHM version 118 or later (the AI Assistant framework was introduced in this release).
• A local AI model endpoint (e.g., http://127.0.0.1:8000/v1) or an external API key from a supported provider.
• Basic familiarity with the command line and package managers.

3. Installing the MCP Library

The MCP library is distributed as a cpanel-mcp package. Install it using the package manager that matches your operating system.

Debian / Ubuntu (apt)

# Update package lists
apt update

# Install the MCP package
apt install cpanel-mcp

# Verify the installation
cpanel-mcp --version

What each command does:

• apt update refreshes the local repository index.
• apt install cpanel-mcp downloads and installs the MCP binaries and systemd service.
• cpanel-mcp --version confirms the installed version.

AlmaLinux / Rocky Linux / RHEL (dnf)

# Refresh metadata
dnf makecache

# Install the MCP package
dnf install cpanel-mcp

# Verify the installation
cpanel-mcp --version

The MCP service starts automatically after installation. Verify its status with systemctl status cpanel-mcp.

4. Registering an AI Model

Every model you want to use must be registered in the MCP database. Registration stores the endpoint URL, authentication method, and a friendly name.

Step‑by‑step (common to both OS families)

# Open the MCP CLI in interactive mode
cpanel-mcp model add

During the interactive session you will be asked for:

• Model ID (e.g., my-gpt-4)
• Endpoint URL (e.g., https://api.openai.com/v1)
• Authentication type (api_key, bearer, none)
• Secret value (the actual API key, entered securely)

Example interaction:

Enter Model ID: my-gpt-4
Enter Endpoint URL: https://api.openai.com/v1
Select auth type [api_key/bearer/none]: api_key
Enter API key: ************
Model "my-gpt-4" added successfully.

For a non‑interactive approach, use JSON input:

cat > /root/model.json <<EOF
{
  "id": "my-gpt-4",
  "endpoint": "https://api.openai.com/v1",
  "auth_type": "api_key",
  "secret": "YOUR_API_KEY"
}
EOF

cpanel-mcp model import /root/model.json

5. Defining Context Scopes

cPanel ships with a set of predefined scopes, but you can create custom ones to suit your workflow.

List existing scopes

cpanel-mcp scope list

Create a new scope (e.g., dns‑manage)

cpanel-mcp scope add dns-manage \
  --description "Create, edit, and delete DNS zones" \
  --whm-endpoints /json-api/addzonerecord,/json-api/editzonerecord,/json-api/removezonerecord

This registers three WHM JSON‑API endpoints under the dns-manage scope.

Verify the new scope

cpanel-mcp scope show dns-manage

The output lists the associated WHM endpoints and any notes you added.

6. Granting Permissions to a Model

Bind the model to the scopes it should be allowed to use. Permissions are explicit – a model can only call what you grant.

Grant dns-manage and mail‑admin to my-gpt-4

cpanel-mcp permission grant my-gpt-4 dns-manage mail-admin

Review current permissions

cpanel-mcp permission list my-gpt-4

Typical output:

Model ID   Scope
---------  -------------
my-gpt-4   dns-manage
my-gpt-4   mail-admin

Revoke a permission

cpanel-mcp permission revoke my-gpt-4 mail-admin

7. Enabling the Assistant in WHM

After MCP configuration, activate the assistant inside WHM so the UI can call it.

1. Log in to WHM as root.
2. Navigate to AI Assistants → Manage Assistants.
3. Click New Assistant and fill in:
   • Name: e.g., “DNS Helper”.
   • Model ID: select my-gpt-4 from the dropdown.
   • Allowed Scopes: tick dns-manage (and any others you granted).
4. Save the assistant. WHM will now display an “Ask AI” button on the DNS management pages.

To edit an existing assistant, click the Edit link next to its entry. Changes in WHM are reflected instantly because the UI queries the MCP service for the current permission set.

8. Auditing and Logging

Regularly review which assistants have been used and what actions they performed.

View recent AI calls

cpanel-mcp audit tail --lines 50

Output shows model ID, scope, WHM endpoint, timestamp, and result status.

Export the audit log for external analysis

cpanel-mcp audit export /var/log/cpanel-mcp-audit.json

Import the JSON into a SIEM or log‑analysis tool to spot anomalies.

Rotate logs

Logs are rotated automatically by logrotate, but you can force a rotation with:

logrotate -f /etc/logrotate.d/cpanel-mcp

9. Updating Model Endpoints and Secrets

When an API key expires or you switch to a new model version, update the registration without recreating the permissions.

Interactive update

cpanel-mcp model edit my-gpt-4
# Follow the prompts to change the endpoint or secret.

JSON‑based update

cat > /root/model-update.json <<EOF
{
  "id": "my-gpt-4",
  "endpoint": "https://api.openai.com/v1",
  "auth_type": "api_key",
  "secret": "NEW_API_KEY"
}
EOF

cpanel-mcp model import /root/model-update.json --replace

The --replace flag tells MCP to overwrite the existing record while preserving all granted scopes.

10. Removing an Assistant and Cleaning Up

To retire an AI Assistant, follow these steps to ensure no dangling permissions remain.

1. In WHM, go to AI Assistants → Manage Assistants and delete the assistant entry.
2. On the command line, revoke all permissions for the model:

# List permissions first (optional)
cpanel-mcp permission list my-gpt-4

# Revoke each scope
cpanel-mcp permission revoke my-gpt-4 dns-manage
cpanel-mcp permission revoke my-gpt-4 mail-admin

1. Remove the model from MCP:

cpanel-mcp model delete my-gpt-4

After deletion, the model ID no longer appears in cpanel-mcp model list, and any future attempts by WHM to call it will be rejected.

Conclusion

cPanel’s AI Assistants, combined with the Model Context Protocol, give you powerful automation while keeping tight control over what each model can do. By registering models, defining precise scopes, granting only the necessary permissions, and regularly auditing activity, you can safely use AI to streamline DNS, mail, SSL, and other server‑side tasks. The steps above cover installation, configuration, updates, and clean‑up for both Debian/Ubuntu and AlmaLinux‑based systems, ensuring a consistent workflow regardless of your server’s distribution.