Skip to content

api-mcp.md

Latest commit

 

History

History
183 lines (150 loc) · 8.52 KB

api-mcp.md

File metadata and controls

183 lines (150 loc) · 8.52 KB
Raw

REST API and MCP

CloudPanel Gateway exposes a secure automation control plane through two network interfaces backed by the same scoped-token, policy, audit, and typed root-helper model. CloudPanel's clpctl surface is one compatibility adapter; the gateway also supplies operational capabilities such as site diagnostics, release delivery, Node runtime lifecycle management, backups, and cron jobs.

Automation interfaces

  • REST API is intended for platform services, deployment pipelines, and conventional integrations.
  • MCP is the AI-native interface. Agents discover typed tools and receive structured results instead of parsing terminal output.
  • Local CLI is intentionally separate and root-only. It bootstraps tokens, maps gateway domains, and enables or disables server-wide policy gates.

Neither REST nor MCP is a remote shell. Every operation has a fixed schema, validation rules, scope requirement, timeout, and redacted audit event.

The public gateway uses bearer authentication for every endpoint except /healthz and /readyz. Do not expose the loopback listener directly; map a TLS-enabled CloudPanel reverse proxy first.

REST endpoints

Endpoint Required scope
GET /healthz, GET /readyz None
GET /openapi.json, GET /docs docs:read
GET /metrics metrics:read
POST /v1/sites sites:write
POST /v1/actions/{action} Action-specific scope
POST /v1/artifacts artifacts:write
POST /v1/artifacts/uploads/begin artifacts:write
POST /v1/artifacts/uploads/{upload_id}/chunk artifacts:write
POST /v1/artifacts/uploads/{upload_id}/complete artifacts:write
GET /v1/sites/{domain}/logs/sources logs:read
POST /v1/sites/{domain}/logs/query logs:read (raw needs admin)
POST /v1/sites/{domain}/logs/diagnose logs:read
GET /v1/sites/{domain}/settings sites:read
PATCH /v1/sites/{domain}/settings/root-directory sites:write
POST /v1/sites/{domain}/settings/site-user/password/rotate site-users:write
GET / PATCH /v1/sites/{domain}/php php:read / php:write
GET / PATCH /v1/sites/{domain}/pagespeed pagespeed:read / pagespeed:write
POST /v1/sites/{domain}/pagespeed/purge cache:purge
GET /v1/sites/{domain}/tls tls:read
POST /v1/sites/{domain}/deployments files:write + file.deploy_artifact policy
POST /v1/sites/{domain}/deployments/root files:write + file.deploy_root policy + replace:true + confirm:true
GET / POST /v1/sites/{domain}/backups backups:read / backups:write
POST /v1/sites/{domain}/backups/{backup_id}/restore backups:write + backup.restore policy + confirm:true

Example:

curl --fail-with-body \
  -H "Authorization: Bearer $CLOUDPANEL_GATEWAY_TOKEN" \
  https://panel.example.com/v1/sites/app.example.com/settings

The OpenAPI document on the running service is authoritative for JSON request and response schemas. Responses include an X-Request-ID; include one in a support request when reporting an issue.

CloudPanel compatibility actions

POST /v1/actions/{action} takes a JSON object with an args map. Only the following actions are accepted: cloudflare.update_ips, CloudPanel basic-auth and release-channel controls, database create/delete/import/export/master credentials, Let's Encrypt/manual certificate operations, all supported site types and site deletion, permission reset, CloudPanel user management, vhost-template management, and Varnish purge.

The complete, version-specific action names, fields, and policy requirements are exposed through /openapi.json and MCP tool discovery. There is no arbitrary clpctl endpoint. These actions are complemented by gateway-native tools for logs, settings transactions, artifact delivery, backup, application runtime, and cron workflows.

MCP

The MCP endpoint is /mcp using Streamable HTTP. It accepts the same bearer token and validates browser Origins against localhost, configured allowed hosts, and mapped gateway domains.

[mcp_servers.cloudpanel-gateway]
url = "https://panel.example.com/mcp"
bearer_token_env_var = "CLOUDPANEL_GATEWAY_TOKEN"

In addition to a typed MCP tool for each allowed CloudPanel compatibility action, the gateway provides these named operational tools:

  • cloudpanel_site_logs_list_sources
  • cloudpanel_site_logs_query
  • cloudpanel_site_logs_diagnose
  • site_get_settings
  • site_update_root_directory
  • site_rotate_user_password
  • php_get_settings, php_update_settings
  • pagespeed_get_settings, pagespeed_update_settings, pagespeed_purge_cache
  • tls_get_status
  • file_deploy_artifact
  • artifact_begin_upload, artifact_upload_chunk, artifact_complete_upload
  • site_deploy_root_artifact
  • site_backup_create, site_backup_list, site_backup_restore

Tools return structured JSON. A log diagnosis offers deterministic evidence such as HTTP error rates, upstream failures, PHP fatal/timeout/memory errors, permission failures, missing files, and common database connection errors. It does not apply a fix.

Managed artifacts

Database transfer, manual certificate, and vhost-template file inputs must be created through POST /v1/artifacts. The gateway stores them in a restricted directory and expires them after one hour. User-supplied absolute file paths, shell snippets, and arbitrary Nginx/PHP/PageSpeed directives are rejected.

ZIP deployments use the same managed artifact flow, but accept only validated ZIP archives up to 100 MiB compressed. Archive traversal, duplicate entries, symlinks, devices, and excessive expansion are rejected. The target directory must be relative to the resolved site root; replacing non-empty content needs both replace:true and confirm:true.

MCP clients can upload local archives without a shell or external URL by using the three upload tools. Begin the upload with its exact number of chunks, send sequential base64 chunks of at most 1 MiB, then complete it to receive the short-lived artifact_id. Upload sessions and artifacts are token-owned and expire after one hour.

site_deploy_root_artifact is intentionally separate from directory deployment. It requires the file.deploy_root local policy and both replace:true and confirm:true; before the atomic root-directory swap, the root helper creates an encrypted files safety backup.

TLS and backups

tls_get_status reports the active leaf certificate's issuer, subject, serial, expiry, SANs, vhost/CloudPanel-record consistency, and an expiry-based renewal_health. It deliberately does not claim that a renewal job succeeded, because CloudPanel has no reliable renewal-history primitive.

Backups are encrypted local recovery objects, not network downloads. They can contain files, CloudPanel-related databases, or both. They expire after seven days and share a 10 GiB retention quota. Restore always creates a matching pre-restore safety backup first, then requires explicit confirmation and the local backup.restore policy.

Static and Node.js releases

Static sites add static_get_settings, static_update_routing, and static_deploy_release. The routing tool only edits its own managed SPA fallback block and uses the Nginx validation/commit service.

Node.js adds project_inspect_artifact, site_build_release, node_get_settings, node_update_settings, node_get_status, node_restart, node_deploy_release, node_list_releases, and node_rollback_release. Node releases use node:read, node:write, node:deploy, and node:build scopes as appropriate. Server builds require the locally enabled node.server_build policy; activation requires node.deploy_release; runtime changes and restarts require node.runtime_manage.

The REST equivalents are POST /v1/projects/inspect, POST /v1/sites/{domain}/builds, GET|PATCH /v1/sites/{domain}/node, GET /v1/sites/{domain}/node/status, POST /v1/sites/{domain}/node/restart, GET|POST /v1/sites/{domain}/node/releases, POST /v1/sites/{domain}/node/rollback, and GET|PATCH /v1/sites/{domain}/static plus POST /v1/sites/{domain}/static/deploy.

Site cron jobs

cron_list, cron_create, cron_update, and cron_delete manage CloudPanel's persisted site cron jobs. REST equivalents are GET|POST /v1/sites/{domain}/cron-jobs and PATCH|DELETE /v1/sites/{domain}/cron-jobs/{job_id}. Reads require cron:read; mutations require cron:write and the current revision. Deletion requires confirm=true. Typed runners are preferred; raw_command requires the root-only cron.raw_command policy and explicit confirmation.