Theme

Connect your AI agent to Syncplify Server! ​

This article assumes ss-mcp is installed where the agent runs (see Download and install the MCP adapter). What follows is the same for every client: create a token, tell the client how to start the adapter, check it once from a terminal.

1. Create the automation token ​

The adapter never signs in with an operator's password. It uses an automation token, a credential that belongs to the operator who creates it and can do at most what that operator can do.

  1. Once per server, a SuperAdmin turns tokens on: Global Configuration, Automation, enable automation tokens, save.
  2. Sign in to the console of the operator the agent will act for and open Automation tokens:
    • in the Admin console of a virtual site, for an agent that manages that site (users, storage, scripts, site settings): the token is an adm token;
    • in the SuperAdmin console, for an agent that manages the whole server (virtual sites, nodes, the cluster, updates, the license): the token is an sa token.
  3. Create the token:
    • Name it after the agent and the machine, for example claude-desktop-alice-laptop. One token per agent and per machine keeps the audit trail readable and lets you revoke one without touching the others.
    • Leave Read only on for a first agent. Turn it off later, for an agent that is meant to change things; every change still goes through a preview and your confirmation.
    • For an Admin token, choose the permissions the agent needs and no more. An agent that answers questions about accounts needs Users and Dashboard; one that manages storage adds VFS; one that reviews security adds Shield and Reports.
    • Grant Service actions only to an agent that is meant to restart or drain nodes, start and stop sites, apply updates, renew certificates or terminate sessions.
    • Set the address allow list when the machine the adapter runs on has a fixed address.
    • Choose an expiry; the policy sets the default and the cap.
  4. Copy the token when it is shown. It is shown exactly once and starts with ssat_.

2. Configure the client ​

Every MCP client starts the adapter as a child process and talks to it over its standard input and output. The adapter needs three things: --server, the address of the console (https://host:6443); --plane, adm for an Admin token or sa for a SuperAdmin token; and the token in the SS_MCP_TOKEN environment variable. The token is never an argument (the adapter refuses a --token flag), so that a process list, a shell history or a copied command line can never leak it.

Claude Desktop ​

Open Settings, Developer, Edit Config. On Windows the file is %APPDATA%\Claude\claude_desktop_config.json. Add the syncplify entry:

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 Claude Desktop completely and start it again; the Syncplify tools appear in the tools menu of a conversation. On macOS the file is ~/Library/Application Support/Claude/claude_desktop_config.json, and because there is no macOS build of the adapter the command is ssh to a Linux machine that has it (see Running the adapter on another machine).

Claude Code ​

One command registers the server for every project of your user:

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

Without --scope user the server belongs to the current project only. To share the configuration with a team through the repository, write .mcp.json at the root of the project and let each developer's environment supply the token, so that the committed file holds no secret:

json
{
  "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. The format is the same mcpServers object as Claude Desktop (command, args, env). Enable the server under Settings, MCP.

Visual Studio Code ​

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

json
{
  "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 program that starts stdio MCP servers works the same way: the path of the executable, the two arguments, the environment variable. The adapter opens no port and has no URL.

Running the adapter on another machine ​

The adapter can live on a Linux machine other than the agent's and be reached over SSH. This keeps the token off laptops, gives a Mac a way in, and lets a team share one installation while each person keeps their own token. Install the adapter there, store the token in a file only that account can read, and make the client's command an SSH session:

json
{
  "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, -T asks for no terminal, and the adapter on the far machine speaks the protocol through the SSH channel exactly as it would through a local pipe.

3. Check it from a terminal ​

Before the agent starts the adapter for the first time, run it yourself with the same settings and --check:

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

It connects, prints who the token is and what it may do, compares the server's specification with its own, 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
  ...

If this fails, the agent would fail the same way: the printed refusal (wrong plane, revoked token, tokens disabled, certificate) is the whole problem. If it succeeds, start the client and ask the agent something simple, such as "how many users does this site have?". The agent lists the users and answers; nothing is changed by a question.

Keep the token safe

  • The token is a credential. Never paste it into a chat with the agent, into a ticket, or into a committed file; the ${SS_MCP_TOKEN} and ${input:...} forms above exist so that files stay clean.
  • Rotate it by creating a new one and revoking the old one in the console; the agent picks up the new value at its next start.
  • Revoke it the moment the machine that holds it is lost. The agent is cut off within seconds on every node of a cluster.

Next ​

What to ask your AI agent: worked examples, the confirm step as you will see it, and the limits.