The MCP adapter

ss-mcp is a stand alone server for the Model Context Protocol, the way Claude Desktop, Claude Code and other AI agents connect to tools. It exposes the management API of one Syncplify Server! as tools, with exactly the rights of the automation token it runs with. It is a separate download, not part of the server installer: it runs where the agent runs, adds no listener to the server, and talks to the server over the same HTTPS REST API every console uses.

The adapter holds no business logic. Every tool is one operation of the served specification; what the agent can do is what the token can do over REST, nothing more. It administers the server only: it never lists folders or reads files. Agents that move files use SFTP, FTPS or HTTPS with a user account, like any other client.

It needs Syncplify Server! 8.8.0 or newer and offers everything the 8.10.0 API has. Against an older server it leaves out the tools that server does not have.

Installing it

1. Download the ss-mcp build for the machine the agent runs on (Linux x86 64, Linux ARM 64 or Windows x86 64) and put it on the path.
2. Create an automation token for the operator the agent acts for. Make it read only unless the agent is meant to change things, narrow its permissions to what the agent needs, and give it the serviceActions scope only if the agent is meant to restart or drain nodes, start and stop sites, update the software, renew certificates or terminate sessions.
3. Configure the MCP client. The token goes in the environment, never on the command line.

Claude Desktop, in claude_desktop_config.json:

{
  "mcpServers": {
    "syncplify": {
      "command": "/usr/local/bin/ss-mcp",
      "args": ["--server", "https://files.example.com:6443", "--plane", "adm"],
      "env": { "SS_MCP_TOKEN": "ssat_..." }
    }
  }
}

Claude Code:

claude mcp add syncplify -e SS_MCP_TOKEN=ssat_... -- /usr/local/bin/ss-mcp --server https://files.example.com:6443 --plane adm

Any other MCP client: run ss-mcp as a stdio server with the same arguments and environment.

Settings

Flag	Environment variable	Meaning
--server	SS_MCP_SERVER	The base URL of the console, https://host:6443. Required.
--plane	SS_MCP_PLANE	sa for a SuperAdmin token (the whole server), adm for an Admin token (one virtual site). Required: a token works only on the plane that minted it.
	SS_MCP_TOKEN	The automation token.
--token-file	SS_MCP_TOKEN_FILE	A file holding the token, for clients that cannot set an environment variable safely.
--read-only	SS_MCP_READ_ONLY	Offer read tools only, whatever the token allows.
--ca-cert	SS_MCP_CA_CERT	A PEM file with the certificate authority that signed the server's certificate, for servers with a private authority.
--insecure		Turns certificate verification off. Refused unless SS_MCP_ALLOW_INSECURE=1 is also set, so that a copied command line cannot silently turn it off. Prefer --ca-cert.
--log-level	SS_MCP_LOG_LEVEL	What the adapter writes to its standard error: trace, debug, info (default), warning or error.
--check		Connects, prints the token's scopes, the specification comparison and the tools it would offer, and exits. The first thing to run when something does not work.
--version		Prints the version and exits.

The adapter verifies the server's certificate like a browser does, never follows redirects (a redirect would carry the token elsewhere), uses no proxy, and never writes the token to its log.

What the agent sees

The tool list is the token's scopes, applied to the operations of the API:

Tool kind	Offered when	Examples
read	the token may read the object (View or Edit permission on the Admin plane, always on the SuperAdmin plane)	list_users, get_vfs, get_cluster_status, list_webhooks
write	the token is not read only and holds the Edit permission for the object	create_user, update_vfs, replace_site_config, create_webhook
destructive	same as write; marked so the agent treats it with care	delete_user, delete_vfs, clear_shield_bans
service	the token has the serviceActions scope	terminate_session, start_vsite, drain_cluster_node, apply_update, renew_acme_certificates

On the SuperAdmin plane the tools are about the whole server: virtual sites, nodes, the global configuration, the cluster, updates, the license, node certificates. On the Admin plane they are about one virtual site: users, storage, scripts, secrets, the site configuration, LDAP, user SSO providers, certificates and keys, Shield, reports, sessions, webhooks. Tools that change an object come in two shapes: update_* changes the given fields (a PATCH), replace_* replaces the object whole (a PUT). The adapter tells the agent to prefer update_*.

What a token can never do is not a tool either: nothing about operator accounts, passwords, second factors, passkeys, operator SSO providers, backup and restore, or token management. The server refuses those routes to every token (see What a token can do), and the specification marks them with x-syncplify-token-access: forbidden.

The list is not static. The adapter reads the token's scopes when it starts, every five minutes, and right after the server refuses a call for lack of permission. When an operator narrows the token or the owner loses a permission, the corresponding tools disappear from the agent's list; when they widen, tools appear. Revoking the token ends every call with the automationTokenRevoked refusal and empties the list at the next refresh.

Besides the tools, the adapter publishes reference material as MCP resources, so the agent can read before it acts:

Resource	Content
syncplify://openapi	The specification the server serves (when serveOpenApi is on), else the one the adapter was built with.
syncplify://events	The log event catalog as the server reports it.
syncplify://reason-codes	The reason codes page.
syncplify://manual	An index of the manual pages that matter to an agent.
syncplify://schema/{Name}	The full schema of one object, such as syncplify://schema/User. Tool arguments name it where they summarize a nested object.

The confirm flow

Every tool that changes something is two steps, and the agent is told so in the tool description.

1. The agent calls the tool without confirm. The adapter reads the object for its ETag, runs the operation with dryRun=true (see Safe writes), and answers with the server's dry run result: whether the write would be accepted, the field level difference it would make, the other objects it would touch, plus a confirmToken and the moment it expires. Nothing has changed on the server.
2. The agent shows the preview to the person and, when they agree, calls the same tool with the same arguments plus confirm set to the token. The adapter executes the operation with If-Match set to the ETag of the preview and an Idempotency-Key derived from the confirmation.

The confirmation token is signed with a key that exists only in that adapter process and is bound to the tool, the exact arguments and the ETag; it is valid for ten minutes. A confirmation presented with different arguments, for another tool, after a restart or after ten minutes is refused, and the agent is told to start over. A dry run that says the write would be refused returns the refusal and no token: there is nothing to confirm. If the object changed between the preview and the confirmation, the server answers 412 and the adapter tells the agent to start over without confirm. Because the idempotency key is derived from the confirmation, an agent that retries a confirmed create gets the original answer instead of a second object.

A few writes persist nothing and skip the step: sending a test email through given SMTP settings, sending a test delivery to a webhook, trying an LDAP bind, running an ACME readiness check, marking notifications as read. The agent calls them once.

Every answer, in one shape

A tool answers with one JSON document: status (the HTTP status), body (the server's answer), and, when present, etag, total (the X-Total-Count header of a list), location and objectId of a created object, replayed when a create was an idempotent replay, and dryRun. A list too large for one answer is cut and says so in truncated, with the hint to use limit and offset. A refusal carries the server's reason code, the message, the field errors, and a hint for the common cases (412, 403, 401).

Audit

On the server every call of the adapter is a call of the token: audit records carry actorKindtoken, the token in actorToken and the owner as the actor, and refused calls are the token events documented on the automation tokens page. The adapter identifies itself with the User-Agent ss-mcp/<version>, so its traffic is recognizable in the web server log.

Troubleshooting

Symptom	Cause and remedy
ss-mcp exits at start with "the token was not accepted"	Wrong server URL, wrong --plane (an Admin token on sa or a SuperAdmin token on adm), a revoked or expired token, or tokens disabled by policy. Run ss-mcp --check with the same settings and read the refusal.
The agent sees fewer tools than expected	The token is narrower than you think. ss-mcp --check prints the effective View and Edit lists, the read only and serviceActions flags, and every tool offered. Widen the token or the owner's permissions; the list follows within five minutes or at the next refusal.
A write tool answers 403	The token lacks the Edit permission, is read only, or the route needs serviceActions. The adapter refreshes the tool list after such a refusal, so the tool disappears.
A confirmed write answers 412	The object changed between the preview and the confirmation. Call the tool again without confirm.
"the confirmation does not match these arguments or has expired"	The confirming call did not repeat the exact arguments of the preview, or ten minutes passed, or the adapter restarted. Call again without confirm.
A tool the specification documents is not offered	The server is older than the adapter's specification. ss-mcp --check lists the tools left out when serveOpenApi is on; without it the adapter cannot compare and offers everything, and the server answers 404 to the operations it lacks.
Certificate errors	The server uses a private authority: pass it with --ca-cert. Do not turn verification off.