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. How to work with the agent once it is connected, with worked examples, is on Working with an AI agent.

Getting the adapter

The adapter is versioned on its own (ss-mcp 1.0.0 ships with Syncplify Server! 8.10.0) and is neither installed nor updated by the server's installer or self update. It is listed on the download page, and the current release is always at these addresses:

Platform	Archive	Contents
Linux, x86 64	https://dl.syncplify.com/ss-mcp-linux-x64.tar.gz	ss-mcp, README.txt
Linux, ARM 64	https://dl.syncplify.com/ss-mcp-linux-arm64.tar.gz	ss-mcp, README.txt
Windows, x86 64	https://dl.syncplify.com/ss-mcp-win-x64.zip	ss-mcp.exe, README.txt
Checksums	https://dl.syncplify.com/ss-mcp-SHA256SUMS.txt	one SHA256 line per archive

Versioned copies (ss-mcp-1.0.0-linux-x64.tar.gz and so on, with their own ss-mcp-1.0.0-SHA256SUMS.txt) stay available next to the current ones, for installations that pin a version. The Windows executable is Authenticode signed by Syncplify, Inc.; the archives themselves are plain, so the checksum file is how a download is verified on every platform.

The adapter runs where the agent runs: on the laptop that runs Claude Desktop, on the workstation that runs Claude Code or an IDE, or on a machine the agent reaches over SSH. It does not have to run on the Syncplify Server! machine, and usually should not. There is no macOS build: a Mac reaches an adapter installed on a Linux machine over SSH, as described under Running the adapter on another machine.

Linux

curl -fsSLO https://dl.syncplify.com/ss-mcp-linux-x64.tar.gz
curl -fsSLO https://dl.syncplify.com/ss-mcp-SHA256SUMS.txt
sha256sum --check --ignore-missing ss-mcp-SHA256SUMS.txt
tar -xzf ss-mcp-linux-x64.tar.gz
sudo install -m 0755 ss-mcp /usr/local/bin/ss-mcp
ss-mcp --version

On an ARM machine replace linux-x64 with linux-arm64. The last command prints ss-mcp 1.0.0 (built <time>, commit <id>).

Windows

1. Download ss-mcp-win-x64.zip and ss-mcp-SHA256SUMS.txt.
2. In PowerShell, Get-FileHash .\ss-mcp-win-x64.zip -Algorithm SHA256 must print the value the checksum file lists for that name.
3. Extract the archive into a directory of its own, for example C:\Program Files\ss-mcp. The Digital Signatures tab of the executable's Properties names Syncplify, Inc.
4. & "C:\Program Files\ss-mcp\ss-mcp.exe" --version prints the version.

Adding the directory to the PATH is optional: every MCP client is given the full path of the executable.

Updating the adapter is replacing the executable with the one from a newer archive while no agent is running it; the adapter stores nothing anywhere else. The adapter and the server need not be updated together: an older adapter simply does not offer what a newer server added, and a newer adapter leaves out at start the tools an older server lacks.

Creating the token

The adapter signs in with an automation token, never with an operator's password. One token per agent and per machine keeps the audit trail readable and makes revocation precise.

1. Once per server, a SuperAdmin turns tokens on under Global Configuration, Automation.
2. The operator the agent will act for creates the token under Automation tokens: in the Admin console for one virtual site (the token works on the adm plane), or in the SuperAdmin console for the whole server (the sa plane).
3. Name the token after the agent and the machine, for example claude-desktop-alice-laptop. Leave it read only until the agent has proved useful and you want it to change things. Give an Admin token only the permissions the agent needs: an agent that answers questions about accounts needs Users and Dashboard, nothing else. Grant serviceActions only to an agent that is meant to restart or drain nodes, start and stop sites, update the software, renew certificates or terminate sessions. Set the address allow list when the machine the adapter runs on has a fixed address.
4. Copy the token when it is shown. It is shown once and starts with ssat_.

Connecting the agent

Every MCP client starts the adapter the same way: as a child process that speaks the protocol on its standard input and output, with --server and --plane as arguments and the token in the SS_MCP_TOKEN environment variable (or in a file named by --token-file). The token is never an argument: the adapter refuses a --token flag, so that a copied command line, a process list or a shell history can never leak it.

Claude Desktop

Claude Desktop reads claude_desktop_config.json, reachable from Settings, Developer, Edit Config. On Windows the file is %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "syncplify": {
      "command": "C:\\Program Files\\ss-mcp\\ss-mcp.exe",
      "args": ["--server", "https://files.example.com:6443", "--plane", "adm"],
      "env": { "SS_MCP_TOKEN": "ssat_..." }
    }
  }
}

Every backslash in a JSON string is doubled. Quit and restart Claude Desktop; the Syncplify tools appear in the tools menu of the conversation. On macOS the file is ~/Library/Application Support/Claude/claude_desktop_config.json and the command is ssh to the machine that holds the adapter (see below).

Claude Code

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

--scope user makes the server available in every project of that user; without it the server belongs to the current project only. For a server a whole team shares through the repository, write .mcp.json at the root of the project and let the token come from each developer's environment, so that the committed file holds no secret:

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

claude mcp list shows whether the server connected; inside a session /mcp lists its tools.

Cursor

Cursor reads ~/.cursor/mcp.json for every project, or .cursor/mcp.json inside one project, with the same mcpServers shape as Claude Desktop (command, args, env). The server is enabled under Settings, MCP.

Visual Studio Code

Visual Studio Code reads .vscode/mcp.json in the workspace (or the user level mcp.json opened with MCP: Open User Configuration). An input of type promptString asks for the token once and keeps it in the secret store, so the file holds no secret:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "ss-mcp-token",
      "description": "Syncplify Server! automation token",
      "password": true
    }
  ],
  "servers": {
    "syncplify": {
      "type": "stdio",
      "command": "ss-mcp",
      "args": ["--server", "https://files.example.com:6443", "--plane", "adm"],
      "env": { "SS_MCP_TOKEN": "${input:ss-mcp-token}" }
    }
  }
}

Any other client

Any client that can start a stdio MCP server works: give it the path of the executable, the two arguments and the environment variable. The adapter opens no port and has no URL; a client that only speaks to remote MCP servers over HTTP needs a stdio bridge of its own.

Running the adapter on another machine

The adapter can run on a machine other than the agent's, reached over SSH, which keeps the token off laptops and gives a Mac a way in. Install the adapter on a Linux machine, put the token in a file only that account can read, and make the client's command an SSH session that runs the adapter:

{
  "mcpServers": {
    "syncplify": {
      "command": "ssh",
      "args": [
        "-T", "mcp@tools.example.com",
        "/usr/local/bin/ss-mcp",
        "--server", "https://files.example.com:6443", "--plane", "adm",
        "--token-file", "/home/mcp/.ss-mcp-token"
      ]
    }
  }
}

The SSH key must authenticate without a prompt (an agent or a key without passphrase in a protected location), -T asks for no terminal, and the ss-mcp process on the far machine speaks the protocol through the SSH channel exactly as it would through a local pipe. Several people can share such a machine, each with their own account, token file and SSH key, and the server's audit trail still tells them apart because each token has its owner.

Checking the setup

Run the adapter once by hand, with the very settings the client will use, plus --check:

SS_MCP_TOKEN=ssat_... ss-mcp --server https://files.example.com:6443 --plane adm --check

It connects, prints the token's identity and scopes, says whether the server publishes its specification and whether any tool was left out for a server that lacks it, lists every tool the agent will see, and exits:

server:   https://files.example.com:6443
plane:    adm
token:    2wXk...q7 (claude-desktop-alice-laptop) owned by alice, virtual site main
expires:  2027-02-01T00:00:00Z
readOnly: true (adapter flag false)
service:  false
view:     Dashboard, Users
edit:
server specification: 8.10.0, 0 operations unknown to this adapter, 0 tools left out
tools offered: 31
  get_dashboard_stats
  get_user
  ...

A refusal at this point is printed with the server's reason code and is the whole problem: fix it here, before the agent ever starts the adapter.

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, checking the release channel for an update. 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
The client reports that the server failed to start, or shows no Syncplify tools	The path in the client configuration is wrong (on Windows every backslash in JSON is doubled), the file is not executable, or the environment block lacks the token. Run the exact command from a terminal with the same environment, with --check: the adapter prints the reason on its standard error and exits.
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 token is never accepted on the command line"	By design. Put it in SS_MCP_TOKEN or in a file named by --token-file.
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.
An antivirus or Windows SmartScreen holds the executable back	Verify the checksum against ss-mcp-SHA256SUMS.txt and the Authenticode signature (Syncplify, Inc.) in the file's Properties before allowing it.