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),userCodeandexpiresAt. 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.
| Input | Required | Default | Meaning |
|---|---|---|---|
action | no | start | start, status to check completion, or cancel to abandon it. |
permissions | no | hosting.sitesRead | Explicit permissions to request, from the list below. |
name | no | host-based CLI name | Name shown on the authorization page. |
renewable | no | unset (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. |
flow | no | auto | auto, browser or device. Set it only to override the choice. |
lifetime | no | none | 1h, 1d, 7d or 30d: a suggestion; the user decides. Above 1h needs renewable. |
timeout_seconds | no | 300 (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:
| Permission | Capability |
|---|---|
hosting.sitesRead | List and inspect sites (required by every hosting operation). |
hosting.filesRead | List files and read individual files. |
hosting.filesWrite | Create and replace individual files. |
hosting.filesDelete | Delete individual files. |
hosting.deploy | Deploy production/preview content, promote preview, and change missing-page handling. |
hosting.download | Download the deployable snapshot. |
hosting.downloadSensitive | Include protected and user-generated content in a download. |
hosting.analyticsRead | Read hosting analytics. |
hosting.analyticsManage | Change analytics configuration. |
forms.create | Create and publish a basic form. |
forms.edit | Edit 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:
| Task | Permissions |
|---|---|
| Inspect a site | hosting.sitesRead |
| Read files | hosting.sitesRead, hosting.filesRead |
| Edit individual files | hosting.sitesRead, hosting.filesRead, hosting.filesWrite |
| Remove files | add hosting.filesDelete |
| Deploy a directory | hosting.sitesRead, hosting.deploy |
| Download a snapshot | hosting.sitesRead, hosting.download |
| Include user content | add hosting.downloadSensitive |
| Build or edit a form | forms.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:
startwith the samepermissions,name,renewable,flowandlifetimeas the one already in flight returns that same URL or code with"reused": true.startwith 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.cancelends the in-flight sign-in and reportscancelled; it reportsnot_pendingwhen 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.
{ "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:
{ "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
iframeAutoHeightvariant 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
jsonScriptsubmit helper for a site's own themed form (replaced bycapScriptwhen the form is Cap-protected); - the optional public Cap.js
botProtectionconfiguration and a mode-specificcapScriptexample 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.
{
"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" }
]
}nameandfieldsare required;fieldstakes 1–100 entries.slugandtitleare optional.submit_labeldefaults toSubmit;success_messagedefaults toThank you. Your response has been submitted.notification_emails,origins, andorigin_sitesare optional and default to[]; each caps at 100 entries.bot_protectiondefaults tointeractive. Chooseinvisiblefor a programmatic Cap solve after local validation, ordisabledfor a legacy integration that submits no token.notification_emailslists 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:
{
"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.sitesReadwhenorigin_sitesis used
describe_form
Describes a form the way it is authored, rather than the way it is submitted to. Read this before editing one.
{ "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
botProtectionconfiguration (nullwhen protection is disabled); - the live definition’s id, version, revision, heading, submit label, and success message;
pages[].fields[]in document order—each with thekeythat addresses it, its type in the same vocabularycreate_basic_formspeaks, its label, whether it is required, its constraints, and its enclosing section when it has one;editableper field, pluspreservedPropertiesfor stored detail outside this vocabulary andlockedPropertiesfor 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;editableandblockedReasonfor 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:
{
"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_fieldtakes the same field shape ascreate_basic_form. Position it withbefore,after, orpage; the default is the end of the last page. An anchor inside a section inserts into that section.update_fieldchanges only the properties it names:label,required,placeholder,options,enable_other,min,max,step,min_length,max_length,fields(contact parts), andnew_keyto rename the submission key. Ahiddenfield permits onlylabelandnew_key.nullclears 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_fieldremoves a field, and a section removes the fields inside it.move_fieldrepositions 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
publishis false - Idempotent: no
- Permission:
forms.edit
update_form_bot_protection
Idempotently configures the form’s public Cap.js protection without changing fields or definitions:
{ "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:
{
"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.sitesReadwhen 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.
{
"site": "example.com",
"path": "wp-content/themes",
"recursive": true
}| Argument | Required | Default | Meaning |
|---|---|---|---|
site | yes | — | Site UUID or hostname. |
path | no | "" | Remote directory relative to the document root. |
recursive | no | false | Include 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.
{
"site": "example.com",
"remote_path": "index.html",
"local_path": "/absolute/project/index.html",
"overwrite": false
}| Argument | Required | Default | Meaning |
|---|---|---|---|
site | yes | — | Site UUID or hostname. |
remote_path | yes | — | Remote file relative to the document root. |
local_path | yes | — | Absolute destination; inside an MCP root when configured. |
overwrite | no | false | Replace an existing regular local file. |
Permission: hosting.filesRead.
put_file
Creates or replaces one regular hosted file from the MCP process filesystem.
{
"site": "example.com",
"local_path": "/absolute/project/index.html",
"remote_path": "index.html",
"etag": "\"etag-from-list\"",
"create_only": false
}| Argument | Required | Default | Meaning |
|---|---|---|---|
site | yes | — | Site UUID or hostname. |
local_path | yes | — | Existing regular file; inside an MCP root when configured. |
remote_path | yes | — | Remote destination relative to the document root. |
etag | no | — | Replace only if the current ETag matches. |
create_only | no | false | Fail if the path already exists. |
The manager queues cache invalidation after a successful write. Permission: hosting.filesWrite.
delete_file
Deletes one regular hosted file.
{
"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.
{
"site": "example.com",
"local_root": "/absolute/project/dist",
"target": "preview",
"ignore": ["*.map"],
"allow_empty": false
}| Argument | Required | Default | Meaning |
|---|---|---|---|
site | yes | — | Site UUID or hostname. |
local_root | yes | — | Existing real directory inside an MCP root. |
target | no | production | production or the separate preview slot. |
ignore | no | [] | Additional gitignore-style patterns. |
ignore_file | no | .zynohostingignore | Absolute path to an alternate ignore file inside an allowed MCP root. |
allow_empty | no | false | Permit 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:
{ "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
{ "site": "example.com", "force": false }| Argument | Required | Default | Meaning |
|---|---|---|---|
site | yes | — | Site UUID or hostname. |
force | no | false | Bypass 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
{ "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
{ "site": "example.com", "mode": "single-page-application" }| Argument | Required | Meaning |
|---|---|---|
site | yes | Site UUID or hostname. |
mode | yes | 404-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
{ "site": "example.com", "runtime": "php", "phpVersion": "8.3" }| Argument | Required | Meaning |
|---|---|---|
site | yes | Site UUID or hostname. |
runtime | yes | static (PHP off) or php (PHP on). |
phpVersion | no | A 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
{ "site": "example.com", "environments": ["production"], "lifetimeDays": 90, "permissions": ["hosting.sitesRead"], "ci": "github" }| Argument | Required | Meaning |
|---|---|---|
site | yes | Site UUID or hostname the user named. |
environments | yes | production, preview, or both. |
lifetimeDays | no | 30, 90, 180, or 365. The user chooses when approving. |
permissions | no | Extra permission keys such as hosting.sitesRead. Leave out unless the user asked; the approver can remove any. |
ci | no | github, 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.
{
"site": "example.com",
"local_root": "/absolute/project/site-copy",
"include_sensitive": false
}| Argument | Required | Default | Meaning |
|---|---|---|---|
site | yes | — | Site UUID or hostname. |
local_root | yes | — | Absolute new or empty destination inside an MCP root. |
include_sensitive | no | false | Include 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:
{ "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:
| Category | Tools | Review expectation |
|---|---|---|
| Remote read | list_sites, get_site, list_forms, get_form_integration, describe_form | Safe for routine discovery. |
| Local write | get_file, apply_download | Confirm the destination and overwrite behavior. |
| Remote mutation | create_basic_form, update_form, update_form_bot_protection, update_form_origins, set_not_found_handling, set_runtime, revoke_deploy_token, file/deploy apply tools | Review form/site, fields, origins, paths, and plans. |
| Token request | request_deploy_token, deploy_token_status, list_deploy_tokens | The user approves in ZynoSuite. Never ask them to paste a token. |
| Plan only | plan_deploy, plan_download, plan_promote | Inspect 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.