Skip to content

MCP tool reference ​

All tools return JSON as structured content and as a text content block. Argument names use snake case. There are 23 tools.

Every tool except login, list_logins and use_login also accepts an optional tenant (a login id, tenant id, or tenant name from list_logins) and an optional account (an email or account id). They pick which saved login to use for that one call and never change the default. A tenant with several accounts signed in needs account (or the full login id), otherwise the call fails with login_ambiguous. Omit it to use the default login. The tool schemas show it, so it is not repeated in the tables below.

Site discovery ​

login ​

Starts a sign-in from the MCP process, then saves the resulting scoped credential for subsequent MCP calls. Use it when no login is saved, when the explicitly requested domain is unavailable in the current login context, or to add a login for another tenant. It chooses the flow itself:

  • Browser flow: where a browser can open on the computer running the MCP. The tool result holds a one-time browserUrl, and the server also tries to open it.
  • Device flow (link and code): over SSH or on a machine with no display. The tool result holds verificationUri, verificationUriComplete (the link with the code filled in), userCode and expiresAt. Give the user the link and the code verbatim. They open it on any device, check that the code matches, pick how long the access lasts, tick the confirmation box, and approve. The agent never opens the link or approves it. The device code itself is never returned.

After the person finishes, call it with action: "status" until it reports authenticated. The status then includes tenant, tenantName, account, grantExpiresAt, permissionKeys (what the approver granted) and deniedPermissionKeys (requested but not granted, because the approver does not hold them in that tenant). If any were not granted, tell the user exactly which and what that means, and do not request them again unless asked; tell the user which account and organization it is and ask them to confirm.

InputRequiredDefaultMeaning
actionnostartstart, status to check completion, or cancel to abandon it.
permissionsnohosting.sitesReadExplicit permissions to request, from the list below.
namenohost-based CLI nameName shown on the authorization page.
renewablenounset (renewable if this computer has a credential store)Keep a rotating renewal credential, in the system key store, so the login does not end after 60 minutes. Set false for a one-hour login.
flownoautoauto, browser or device. Set it only to override the choice.
lifetimenonone1h, 1d, 7d or 30d: a suggestion; the user decides. Above 1h needs renewable.
timeout_secondsno300 (browser); until the code expires (device)Time to wait for the sign-in to complete (1–600).

The renewal token can only go in the system store unless the MCP host sets ZYNOHOSTING_CREDENTIAL_STORE=file in its environment. The model cannot choose the file store through a tool input.

permissions is an enumeration. These are the only valid values; a plausible-looking key such as hosting.sitesWrite does not exist, and one invalid entry rejects the whole request rather than granting the remainder:

PermissionCapability
hosting.sitesReadList and inspect sites (required by every hosting operation).
hosting.filesReadList files and read individual files.
hosting.filesWriteCreate and replace individual files.
hosting.filesDeleteDelete individual files.
hosting.deployDeploy production/preview content, promote preview, and change missing-page handling.
hosting.downloadDownload the deployable snapshot.
hosting.downloadSensitiveInclude protected and user-generated content in a download.
hosting.analyticsReadRead hosting analytics.
hosting.analyticsManageChange analytics configuration.
forms.createCreate and publish a basic form.
forms.editEdit a form, its bot protection, and its allowed origins.

Request the narrowest complete set for the stated task, always including hosting.sitesRead for hosting work:

TaskPermissions
Inspect a sitehosting.sitesRead
Read fileshosting.sitesRead, hosting.filesRead
Edit individual fileshosting.sitesRead, hosting.filesRead, hosting.filesWrite
Remove filesadd hosting.filesDelete
Deploy a directoryhosting.sitesRead, hosting.deploy
Download a snapshothosting.sitesRead, hosting.download
Include user contentadd hosting.downloadSensitive
Build or edit a formforms.create, forms.edit, and hosting.sitesRead to add a site’s origins

A token’s scope is fixed for its lifetime; a missing permission means signing in again. Signing in again as the same account in the same tenant replaces and revokes the old login. There is no logout tool; a full sign-out is zynohosting logout in a terminal.

Only one sign-in runs at a time, and the result says which one you received:

  • start with the same permissions, name, renewable, flow and lifetime as the one already in flight returns that same URL or code with "reused": true.
  • start with any different request cancels the in-flight sign-in—closing its loopback listener or cancelling its code on the server, so the old URL or code stops working—and returns a new one with "reused": false. The requested scope is never silently replaced by the earlier one.
  • cancel ends the in-flight sign-in and reports cancelled; it reports not_pending when nothing is in flight, and the normal authenticated status when the person completed sign-in first.

A saved login is one account in one tenant: signing in again as the same account in the same tenant replaces that login; another account or tenant adds a login and makes it the default.

status echoes the pending request’s permissions so a long-running flow can be checked against what was asked for. The tool cannot replace an API key or bearer token injected into the MCP process. Change that injected credential and restart the MCP host instead.

list_logins ​

Lists the saved logins for this environment, one per account and tenant: loginId, accountId, accountEmail, tenantId, tenantName, active (the default), renewable, permissionKeys, deniedPermissionKeys, accessExpiresAt, grantExpiresAt, and expired. It takes no input and changes nothing. When there is more than one login, ask the user which organization to work in before acting, then pass its name or id as tenant.

use_login ​

Makes a saved login the default for later calls, without signing in again. Input: tenant (required: a login id, tenant id, or tenant name) and optional account to narrow it. It clears pending deploy, promote and download plans, because the context changes. It fails with fixed_credential_source when the MCP process was given an API key or token. To use another login for one call only, pass tenant on that tool instead.

list_sites ​

Lists sites authorized for the current credential.

  • Arguments: none
  • Mutates remote state: no
  • Permission: hosting.sitesRead

get_site ​

Gets one explicitly intended, authorized site by UUID or hostname. Do not use this as a way to select a likely deployment domain—ask the user whenever the project does not name one.

json
{ "site": "example.com" }
  • site — required site UUID, primary hostname, vanity hostname, or alias
  • Mutates remote state: no
  • Permission: hosting.sitesRead

ZynoForms ​

list_forms ​

Lists the tenant’s existing forms. Each item includes form metadata, the customer-facing direct URL, and a ready-to-use iframe snippet.

  • Arguments: none
  • Mutates remote state: no
  • Permission: authenticated tenant access

get_form_integration ​

Returns everything needed to connect a site to the current live version of one form:

json
{ "form": "contact-us" }

form is a form UUID or exact slug; names are intentionally not accepted. The result includes:

  • direct and iframe embed code, including an iframeAutoHeight variant that resizes the frame to the form;
  • stable form-UUID public definition and submission URLs, version-pinned to the live definition, plus the current-definition URL;
  • the live definition ID, version, and revision;
  • the response contract keyed by stable field alias;
  • JSON, URL-encoded, multipart-text, and native HTML examples, plus an instance-scoped jsonScript submit helper for a site's own themed form (replaced by capScript when the form is Cap-protected);
  • the optional public Cap.js botProtection configuration and a mode-specific capScript example that submits with a Cap proof;
  • accepted content types and the 5 MiB body limit;
  • a warning when an unpublished draft exists.

JSON is the recommended and OpenAPI-advertised submission format. The runtime also accepts application/x-www-form-urlencoded and multipart text fields using names such as responses[email] and responses[contact][firstName]. Public definition and submission endpoints require no credential.

A site that renders its own themed form posts { "responses": { … } } to the submission endpoint with POST and Content-Type: application/json. A stored submission answers 200 with { "ok": true }; failures answer { "error": "<message>" } with 400 (rejected value, duplicate field, unpublished definition, failed verification), 404 (unknown tenant, form, or definition), or 413 (body over 5 MiB).

With interactive Cap protection, the native HTML example pins cap-widget@0.1.56, renders <cap-widget> with the returned apiEndpoint, and names its hidden token field capToken, so the widget posts the proof as part of the form and the page needs no script of its own. The widget is form-associated and carries required, so the browser blocks submission until the visitor solves it. The returned capScript example shows how a custom JSON integration can take the solved token from that widget and include it in the payload without rendering an official ZynoForm.

With invisible protection there is no markup-only path: the generated capScript takes over the HTML example's submit event, solves Cap with new Cap({ apiEndpoint }).solve() from the pinned cap-widget@0.1.56 script, and posts the answers as JSON with the token under the returned tokenField (currently capToken). The markup keeps its action so a page whose script never loads fails loudly on the API instead of navigating with every answer in the query string, and the result carries a warning saying it cannot post by itself. Disabled protection omits Cap entirely, so legacy HTML and JSON integrations remain valid.

For a hidden form field, the response contract identifies its source as urlQueryParameter and includes its urlParameter. It is not a secret: the public form reads that query parameter from its own URL, and generated native HTML enables its hidden control only when the parameter is present. Treat the value as visitor-controlled in every integration.

Use apiEndpoint exactly as returned, trailing slash included—the widget appends its own challenge and redeem paths. Beyond the pinned script, the widget fetches its WebAssembly and pako from cdn.jsdelivr.net and calls the Cap endpoint at runtime, so a page with a strict Content-Security-Policy needs both hosts in script-src and connect-src. A proof is single-use, so each submission needs its own. The API validates the responses before it consumes the proof, so a rejection for a bad field value leaves a solved widget usable; only a spent or expired proof requires verifying again. Cap's endpoint answers any origin, so solving needs no configuration—allowed origins govern the ZynoSuite endpoints only. Both generated scripts post JSON on purpose: a URL-encoded fetch skips the CORS preflight, and the submission endpoint withholds only response headers, so an unlisted origin would have its submissions stored and merely hidden. A native <form> post is a navigation and is unaffected.

  • Mutates remote state: no
  • Permission: authenticated tenant access

create_basic_form ​

Creates a one-page form and immediately publishes version 1. This is deliberately a simple creator rather than the complete ZynoForms authoring model.

json
{
    "name": "Request a quote",
    "slug": "request-quote",
    "title": "Tell us about your project",
    "submit_label": "Send request",
    "success_message": "Thanks—we’ll be in touch.",
    "notification_emails": ["sales@example.com"],
    "origins": ["https://www.example.com"],
    "origin_sites": ["example.com"],
    "bot_protection": "interactive",
    "fields": [
        { "key": "name", "label": "Name", "type": "text" },
        { "key": "email", "label": "Email", "type": "email" },
        { "key": "message", "label": "Message", "type": "textarea" }
    ]
}
  • name and fields are required; fields takes 1–100 entries.
  • slug and title are optional.
  • submit_label defaults to Submit; success_message defaults to Thank you. Your response has been submitted.
  • notification_emails, origins, and origin_sites are optional and default to []; each caps at 100 entries.
  • bot_protection defaults to interactive. Choose invisible for a programmatic Cap solve after local validation, or disabled for a legacy integration that submits no token.
  • notification_emails lists the To: recipients who receive submission notifications—not a sender or From address—and has no bearing on the recipient domain’s SPF, DKIM, or DMARC records.
  • The input schema is strict; unrecognized keys are rejected rather than ignored.

On a Suite deployment that predates Cap, the API can create the form while ignoring the requested protection setting. In that case this tool returns an error that names the already-created form rather than claiming it is protected. Use disabled explicitly for a legacy deployment, or upgrade the Suite before creating a protected form.

fields accepts text, textarea, email, phone, url, hidden, number, date, select, radio, checkbox, and one contact field. Every field has a unique JavaScript-identifier key; that becomes its stable submission alias. required defaults to true except for hidden fields.

A hidden field accepts only key and label. Its key is its public form URL query-parameter name: for example, ?campaign=spring submits campaign: "spring". It never renders a visible input and is always visitor-controlled; do not use it for secrets or trusted data.

The rendered form and generated HTML enforce required fields in the browser. Custom JavaScript integrations should enforce the returned required contract before submitting; the public API cannot generally require conditionally visible fields.

For select, supply string options. Radio options may be strings or { "title": "Shown label", "value": "submitted-value" }. A contact field has no overall label—the selected details label themselves—and uses this shape:

json
{
    "key": "contact",
    "type": "contact",
    "fields": ["first_name", "last_name", "email", "phone_cell", "address"]
}

Its fields may contain display_name, first_name, last_name, company, birthdate, phone_cell, email, address, and zip. Use zip for ZIP-only collection; address already includes street, ZIP, city, and state.

Exact origins are normalized and deduplicated. Each origin_sites reference expands through get_site to HTTPS origins for its current primary, alias, vanity, and preview hostnames. The result contains the same integration package as get_form_integration.

  • Mutates remote state: yes; creates and publishes
  • Idempotent: no
  • Permission: forms.create; hosting.sitesRead when origin_sites is used

describe_form ​

Describes a form the way it is authored, rather than the way it is submitted to. Read this before editing one.

json
{ "form": "contact-us", "include_draft": true }

form is a form UUID or exact slug. The result contains:

  • the form summary, its current notification emails, and its public Cap botProtection configuration (null when protection is disabled);
  • the live definition’s id, version, revision, heading, submit label, and success message;
  • pages[].fields[] in document order—each with the key that addresses it, its type in the same vocabulary create_basic_form speaks, its label, whether it is required, its constraints, and its enclosing section when it has one;
  • editable per field, plus preservedProperties for stored detail outside this vocabulary and lockedProperties for detail that cannot be rewritten without loss (rich radio options, per-part contact configuration);
  • advanced—the constructs the form holds that these tools preserve but cannot author: sections, conditional rules, multiple pages, themes, translations, CRM contact rules, and review, signature, or display fields;
  • draft—the same structure for the unpublished draft, when there is one, because a draft blocks editing;
  • editable and blockedReason for the form as a whole.

A stored text field carrying inputType: email is reported as email, and one carrying format: large as textarea—the words that produced it.

  • Mutates remote state: no
  • Permission: authenticated tenant access

update_form ​

Changes an existing form in place, publishing a new version by default:

json
{
    "form": "contact-us",
    "name": "Contact sales",
    "notification_emails": ["sales@example.com"],
    "operations": [
        { "op": "add_field", "after": "email", "field": { "key": "budget", "type": "number", "label": "Budget", "min": 0 } },
        { "op": "update_field", "key": "message", "label": "How can we help?", "required": false },
        { "op": "move_field", "key": "terms", "page": 2 },
        { "op": "remove_field", "key": "fax" }
    ]
}

Metadata arguments—name, slug, title, submit_label, success_message, notification_emails—are each optional and applied only when they differ from what the form already holds. notification_emails replaces the list; [] clears it. slug accepts null to remove the public link name.

operations apply in order, each addressing a field by its key (or its UUID when it has none):

  • add_field takes the same field shape as create_basic_form. Position it with before, after, or page; the default is the end of the last page. An anchor inside a section inserts into that section.
  • update_field changes only the properties it names: label, required, placeholder, options, enable_other, min, max, step, min_length, max_length, fields (contact parts), and new_key to rename the submission key. A hidden field permits only label and new_key. null clears an optional constraint. Changing a field’s type is rejected—remove it and add its replacement, since the field’s identity carries its submission history.
  • remove_field removes a field, and a section removes the fields inside it.
  • move_field repositions a field, including into or out of a section.

Fields no operation names keep their UUIDs and every stored property, so an edit never disturbs the rest of the form. Content this vocabulary cannot express—sections, conditions, themes, translations, per-field styling—is carried through untouched. An edit that produces no change writes nothing.

Refused rather than half-applied:

  • a field named by a conditional rule cannot be renamed or removed, and neither can one a review field summarizes;
  • a field whose type is outside the basic vocabulary cannot be updated, only moved or removed;
  • a rich radio option list or a contact field with per-part configuration cannot be replaced, though the rest of that field stays editable;
  • adding a second contact field, a duplicate key, or a bound that contradicts its counterpart.

A form has one shared draft, also used by the ZynoForms builder. While an unpublished draft exists update_form refuses, rather than overwrite work in progress; pass on_existing_draft: "extend" to build on that draft instead. A save quotes the draft revision it was based on—0 when there was none—so a concurrent save is rejected by the API rather than clobbered. Pass expected_definition_id from describe_form to have the edit refused if a different version has gone live in the meantime; it is re-checked immediately before the write, though the API offers no atomic compare-and-publish, so a publish landing in that last instant cannot be detected.

publish defaults to true. With publish: false the result is saved as an unpublished draft and the live form is unchanged. The result is the same integration package as get_form_integration, plus applied (metadata, and definition as published, draft, or unchanged) and a changes list. Metadata is applied before the definition; if the definition step then fails, the error says so.

Removing a field does not affect existing submissions—each is pinned to the definition version it was made against. Renaming a key does break integrations posting the old one.

  • Mutates remote state: yes; publishes a new version unless publish is false
  • Idempotent: no
  • Permission: forms.edit

update_form_bot_protection ​

Idempotently configures the form’s public Cap.js protection without changing fields or definitions:

json
{ "form": "contact-us", "bot_protection": "invisible" }

bot_protection is one of interactive, invisible, or disabled. The tool returns the same integration package as get_form_integration, including the public botProtection config and an appropriate capScript example, plus botProtectionChanged and botProtectionSetting — the setting echoed back in this tri-state vocabulary, where the Suite's own form.botProtectionMode is null for disabled. Repeating the current setting performs no update request. Use disabled only for a legacy integration that must continue submitting without a Cap token.

  • Mutates remote state: yes; only when the requested setting differs
  • Idempotent: yes
  • Permission: forms.edit

update_form_origins ​

Idempotently adds or removes exact form CORS origins:

json
{
    "form": "contact-us",
    "add_origins": ["https://app.example.org"],
    "remove_origins": ["https://old.example.org"],
    "add_sites": ["example.com"],
    "remove_sites": []
}

At least one add/remove list must be non-empty. An origin contains only an HTTP(S) scheme, host, and optional port. Site references expand to all current HTTPS hostnames. Adding and removing the same normalized origin in one request is rejected. A request that produces no change skips the update call.

  • Mutates remote state: yes; additions and removals apply immediately
  • Idempotent: yes
  • Permission: forms.edit; hosting.sitesRead when a site reference is used

A framed form posts { type: "zcx:embed:form-height", formId, height } to its parent on load and on every later height change. iframeAutoHeight already listens for it; a hand-written listener must check event.origin and, when a page embeds more than one form, identify the frame with event.source === frame.contentWindow rather than by formId.

For a static integration overview, read the MCP resource zynoforms://guides/embedding.

Individual files ​

list_files ​

Lists one hosted directory or subtree without following symbolic links.

json
{
    "site": "example.com",
    "path": "wp-content/themes",
    "recursive": true
}
ArgumentRequiredDefaultMeaning
siteyes—Site UUID or hostname.
pathno""Remote directory relative to the document root.
recursivenofalseInclude the complete subtree.

Permission: hosting.filesRead.

get_file ​

Downloads one regular hosted file to the filesystem of the computer running the MCP process.

When one or more local roots are configured, this tool, put_file, plan_deploy, and plan_download constrain their local paths to those roots. When no roots are configured, they can use any absolute path accessible to the MCP process user.

json
{
    "site": "example.com",
    "remote_path": "index.html",
    "local_path": "/absolute/project/index.html",
    "overwrite": false
}
ArgumentRequiredDefaultMeaning
siteyes—Site UUID or hostname.
remote_pathyes—Remote file relative to the document root.
local_pathyes—Absolute destination; inside an MCP root when configured.
overwritenofalseReplace an existing regular local file.

Permission: hosting.filesRead.

put_file ​

Creates or replaces one regular hosted file from the MCP process filesystem.

json
{
    "site": "example.com",
    "local_path": "/absolute/project/index.html",
    "remote_path": "index.html",
    "etag": "\"etag-from-list\"",
    "create_only": false
}
ArgumentRequiredDefaultMeaning
siteyes—Site UUID or hostname.
local_pathyes—Existing regular file; inside an MCP root when configured.
remote_pathyes—Remote destination relative to the document root.
etagno—Replace only if the current ETag matches.
create_onlynofalseFail if the path already exists.

The manager queues cache invalidation after a successful write. Permission: hosting.filesWrite.

delete_file ​

Deletes one regular hosted file.

json
{
    "site": "example.com",
    "remote_path": "obsolete.html",
    "etag": "\"etag-from-list\""
}

etag is optional but recommended. The manager queues cache invalidation after success. Permission: hosting.filesDelete.

Full deployments ​

plan_deploy ​

Builds and stores an exact full-site synchronization plan without mutating the remote site. The site must be the domain the user explicitly chose; never infer it from the project or choose a similar authorized domain.

The optional target is production by default. Choose preview to deploy only the independent preview slot; the plan and apply result include the selected target and its stable URL. A preview apply never promotes automatically.

json
{
    "site": "example.com",
    "local_root": "/absolute/project/dist",
    "target": "preview",
    "ignore": ["*.map"],
    "allow_empty": false
}
ArgumentRequiredDefaultMeaning
siteyes—Site UUID or hostname.
local_rootyes—Existing real directory inside an MCP root.
targetnoproductionproduction or the separate preview slot.
ignoreno[]Additional gitignore-style patterns.
ignore_fileno.zynohostingignoreAbsolute path to an alternate ignore file inside an allowed MCP root.
allow_emptynofalsePermit an empty deployable scope to delete remote content.

The result includes planId, expiry, exact operations, upload bytes, and ignore sources. Permission: hosting.deploy.

apply_deploy ​

Applies an in-memory deployment plan:

json
{ "plan_id": "019f0000-0000-7000-8000-000000000000" }

The plan must come from plan_deploy in the same MCP process and must still be valid. A successful apply consumes it and queues cache invalidation. Permission: hosting.deploy.

Preview promotion ​

plan_promote ​

json
{ "site": "example.com", "force": false }
ArgumentRequiredDefaultMeaning
siteyes—Site UUID or hostname.
forcenofalseBypass only the missing-preview-wp-config.php guard. Saved in the plan.

Reads the explicitly chosen site's current production deployment and both URLs, then stores a plan for up to 15 minutes in this MCP process. It does not change either slot. The result includes planId, siteId, productionUrl, previewUrl, expectedProductionDeploymentId, force (plus forceWarning when true), the shared-resource notice, and expiry. Present both URLs and the notice before applying. Planning does not freeze preview: whatever is in preview at apply time becomes production. Permission: hosting.sitesRead.

Promotion is blocked when production has wp-config.php and preview does not. Set force: true only when the user explicitly asks to override that guard; never retry with force on your own after a rejection. apply_promote has no force argument and uses the choice saved in the plan. The manager and node still recheck the files immediately before rotation.

apply_promote ​

json
{ "plan_id": "c1224591-e7c0-4c44-b1ee-b8afc5676542" }

Renames production to an archive and preview into production through the manager's promote API, creates an empty preview, and waits for serving reconciliation. A background job purges the archive. Nothing is copied, and there is no history or rollback API. The manager rejects a plan if another promotion changed the production generation; ordinary file edits do not advance that generation. Later preview edits leave the promoted files unchanged. A failed reconciliation is reported as a tool error; after the manager accepts the promotion, retrying the same plan resumes polling for up to an hour instead of promoting again. Successful apply consumes the plan. Unknown, expired, consumed, or other-process plan IDs are rejected. Permission: hosting.deploy.

Preview has no separate database and uses the main site’s database. It shares the main site’s storage quota. Database changes from preview can affect the live site. See the CLI feature details.

Site settings ​

set_not_found_handling ​

json
{ "site": "example.com", "mode": "single-page-application" }
ArgumentRequiredMeaning
siteyesSite UUID or hostname.
modeyes404-page (default) or single-page-application.

single-page-application serves /index.html with status 200 for unknown paths unless they end in a listed asset extension (.js, .css, images, fonts, .json, .txt, ...), which still return 404, so client-side routers can handle deep links. The change applies immediately to production and preview and clears the CDN cache, so ask the user first, and prefer pre-rendering every route. Static sites only: it fails with not_found_handling_requires_static on a PHP site. Older managers that do not report notFoundHandling fail with not_found_handling_unavailable. Idempotent; waits for serving reconciliation and returns siteId, site, notFoundHandling, previous, changed, operationId, and status. There is no plan step. Permission: hosting.deploy (plus hosting.sitesRead). get_site reports the current notFoundHandling.

set_runtime ​

json
{ "site": "example.com", "runtime": "php", "phpVersion": "8.3" }
ArgumentRequiredMeaning
siteyesSite UUID or hostname.
runtimeyesstatic (PHP off) or php (PHP on).
phpVersionnoA version such as 8.3, only with php. Omit for the platform default.

Applies immediately to production and preview and clears the CDN cache, so ask the user first. Turning PHP on while not-found handling is single-page-application resets it to 404-page. An unsupported version fails with unsupported_php_version. Idempotent; waits for serving reconciliation and returns siteId, site, phpVersion, previous, changed, status. Permission: hosting.deploy.

Deploy tokens ​

These tools request and manage deploy tokens for CI. They never receive a token, so they cannot show one to the model. The user sees the token once, on the approval page, and puts it in their CI settings.

request_deploy_token ​

json
{ "site": "example.com", "environments": ["production"], "lifetimeDays": 90, "permissions": ["hosting.sitesRead"], "ci": "github" }
ArgumentRequiredMeaning
siteyesSite UUID or hostname the user named.
environmentsyesproduction, preview, or both.
lifetimeDaysno30, 90, 180, or 365. The user chooses when approving.
permissionsnoExtra permission keys such as hosting.sitesRead. Leave out unless the user asked; the approver can remove any.
cinogithub, gitlab, or other, so the page shows the right steps.

Returns requestId, an approval link, and a short code. Give the user the link and code. They check the code, site, and environments, choose a lifetime, and approve. The agent never opens or approves the link, and never asks the user to paste a token into the chat.

deploy_token_status ​

Input: requestId. Reports pending, approved (with keyId, permissionKeys, a short preview, and expiresAt), denied, or expired. It never includes the token.

list_deploy_tokens ​

Input: optional site. Lists token ids, previews, sites and environments, permission keys, approver, expiry, and last use.

revoke_deploy_token ​

Input: keyId. Revokes the token. CI that uses it stops deploying at once. Ask the user first. Idempotent: an id ZynoAuth no longer has returns status: revoked with already_revoked: true.

Complete downloads ​

plan_download ​

Authorizes a deployable or sensitive site snapshot into an allowed local destination.

json
{
    "site": "example.com",
    "local_root": "/absolute/project/site-copy",
    "include_sensitive": false
}
ArgumentRequiredDefaultMeaning
siteyes—Site UUID or hostname.
local_rootyes—Absolute new or empty destination inside an MCP root.
include_sensitivenofalseInclude protected and user-generated content.

Permissions: hosting.download, plus hosting.downloadSensitive when include_sensitive is true.

apply_download ​

Downloads and safely extracts a planned snapshot:

json
{ "plan_id": "c1224591-e7c0-4c44-b1ee-b8afc5676542" }

The plan must come from plan_download in the same MCP process. A successful apply consumes it.

Review guidance for agents ​

Treat these tools as follows:

CategoryToolsReview expectation
Remote readlist_sites, get_site, list_forms, get_form_integration, describe_formSafe for routine discovery.
Local writeget_file, apply_downloadConfirm the destination and overwrite behavior.
Remote mutationcreate_basic_form, update_form, update_form_bot_protection, update_form_origins, set_not_found_handling, set_runtime, revoke_deploy_token, file/deploy apply toolsReview form/site, fields, origins, paths, and plans.
Token requestrequest_deploy_token, deploy_token_status, list_deploy_tokensThe user approves in ZynoSuite. Never ask them to paste a token.
Plan onlyplan_deploy, plan_download, plan_promoteInspect the returned target, scope, and URLs before apply.

The MCP server enforces technical boundaries, but the calling agent or user remains responsible for choosing the intended site and reviewing destructive operations. Never infer a deployment domain. If an explicitly named domain is unavailable, do not substitute another site; offer login so the user can switch contexts. Likewise, never select plan_promote force: true unless the user explicitly requests that override.

Documentation for the ZynoHosting CLI and local MCP server.