What to ask your AI agent

With the adapter connected (see Connect your AI agent), the agent is one more operator of your server: one that works through an automation token and asks before it changes anything. This article shows what a conversation looks like, with an Admin token for a virtual site; the same holds for a SuperAdmin token, where the subjects are virtual sites, nodes, the cluster and updates instead of users and storage.

Tell the agent what it is dealing with

The adapter already tells the agent how to behave: manage the server, never touch files, preview then confirm every change, read an object's schema before building one. Add the context only you know, where your client keeps standing instructions (project instructions in Claude Desktop, CLAUDE.md for Claude Code, the rules file of Cursor):

You manage the Syncplify Server! virtual site "main" through the syncplify MCP server.
This is the production server. Before any change, show me the preview the tool returned
(the diff and the dependents) and wait for my explicit yes; never confirm on your own,
and change one object per confirmation. A user's ID is their sign in name.

Questions and reviews

These need nothing more than a read only token, and a question never changes anything:

• "How many users does this site have, how many are disabled, and which disabled ones still have a public key on file?"
• "Which users can sign in with a password but are not forced to use a second factor?"
• "Which VFS does nobody reference, and which users reference the VFS called archive?"
• "Show the current Shield bans and the strikes behind them, grouped by network."
• "Compare the site's security settings with what the server suggests and list the differences."
• "Who is connected right now, from which addresses, over which protocols?"
• "What happened to uploads and downloads this week compared with last week?"
• "Which log events are about certificates?" and "What does the reason code webrest.token.readOnly mean?" (the adapter gives the agent the event catalog and the reason codes as reference material).

The agent calls the matching tools (list_users, report_vfs_users, list_shield_bans, get_site_config, list_sessions, get_dashboard_stats and so on), pages through long lists, and answers in words. Ask it to show the raw data when you want to see what it saw.

A change, step by step

You: Disable bob's account. He left the company today.

The agent calls update_user for bob with the change {"status": "Disabled"}. Because it is a change, the adapter does not apply it: it asks the server for a dry run and hands the agent the result, which is the server's own account of what would happen:

{
  "status": "confirmationRequired",
  "preview": {
    "valid": true,
    "action": "update",
    "objectId": "bob",
    "diff": { "changed": { "status": { "from": "Enabled", "to": "Disabled" } } },
    "dependents": []
  },
  "confirmToken": "v1.1763633527.VY8iM2...",
  "expiresAt": "2026-11-20T10:22:07Z"
}

Agent: This would change bob's status from Enabled to Disabled and nothing else. Shall I apply it?

You: Yes.

The agent calls update_user again with the same arguments plus the confirmation token, and the change is made. Three things protect you here, and none of them depends on the agent being right:

1. Nothing happened until you said yes. The preview came from a server side dry run; the server stored nothing.
2. What was confirmed is what you saw. The confirmation token is bound to the tool, the exact arguments and the version of the object the preview was computed on. If the agent changed an argument, or if someone else changed bob in the meantime, the server refuses (412) and the agent has to preview again.
3. It is on record. The server's audit trail shows the change made by the token and its owner, exactly like a change made in the console.

What to look at in a preview: diff lists only the fields you asked to change; dependents lists what else the change would touch (the users that reference a VFS you are about to delete, for example); valid is true. A dry run that is not valid comes back with the reasons and no confirmation token: there is nothing to confirm until the agent fixes its request.

Changes that work well

• "Disable bob." and "Enable carol again."
• "Create a read only account for the auditor, public key only, with access to the VFS reports." The agent reads the user schema the adapter publishes before it builds the object, then previews it.
• "Move alice's home to the VFS projects and keep her permissions."
• "Add a webhook that sends every failed sign in to https://hooks.example.com/syncplify." The agent finds the right event block in the catalog.
• "Delete the VFS legacy-share." The agent's tool list marks this as destructive, and the preview lists the users who still reference the VFS. A well instructed agent stops and shows you that list.
• With a SuperAdmin token: "Is the cluster healthy, and is there an update?" (reads), "Apply the update" (a service action, previewed and confirmed; the server then updates one node at a time).

What the agent will not do

• Files. It never lists folders or reads, moves or deletes files. An agent that must move files uses SFTP or FTPS with a user account.
• Operator accounts and credentials. Nothing about Admin or SuperAdmin accounts, passwords, second factors, passkeys, operator sign in providers, backups or tokens. The server refuses those routes to every token.
• Anything its token may not. Restarting or draining a node, starting or stopping a site, applying an update, renewing a certificate and terminating sessions need the serviceActions scope on the token. Without it the tools are simply not there, and the agent says so.
• Bulk changes in one step. One confirmation changes one object. Forty accounts to disable are forty previews and forty answers, which is right for forty decisions and wrong for a migration; a migration is a script against the REST API.

One honest caveat

The adapter cannot see whether the agent showed you the preview. It only knows that the tool was called a second time with a valid confirmation. The instruction to wait for your yes is part of the agent's instructions, and the agent's model is what honours it. The guard that needs no trust is the read only token: give an agent write rights only after you have watched it ask.

Habits that keep it safe

• Start with a read only token. Add Edit permissions one at a time, once the agent has shown it asks first.
• One token per agent and per machine, named after both, with an expiry and an address allow list where the machine has a fixed address. Revoke it the moment the machine is lost or the agent misbehaves.
• Watch what it does. A webhook subscribed to the object change events tells a chat channel about every change an agent makes, as it happens, and the audit trail records each one with the token.
• Never paste the token into the conversation. The agent does not need it; the adapter has it. If it ever shows up in a chat, revoke it.