SmartZone credentials

SZ-MCP stores one SmartZone controller per account. Saving new credentials replaces what was there; there is no list of connections to choose between.

The form

Field	Required	Limit	Notes
Host / FQDN	Yes	253 characters	Bare hostname or IP. No scheme, no path — sz.example.com, not https://sz.example.com/
Port	Yes	1–65535	Defaults to 8443
Username	Yes	200 characters	A SmartZone admin username
Password	On first save	500 characters	Leave blank when editing to keep the stored one
Label	No	100 characters	Your own nickname. Not sent to the controller

Entering a host with a scheme or a path is rejected before anything is contacted, with host must be a bare FQDN or IP (no scheme, no path).

The password is write-only

Once saved, the password is never returned — not to the dashboard, not through the API, not to Claude. The form shows a placeholder (••••••• (saved — leave blank to keep)) rather than the value.

It is stored in Cloudflare D1, encrypted with AES-256-GCM, and decrypted only in memory when a new service ticket has to be minted. See Where the password lives.

That is also why the password is optional on later saves: you can correct the host, port, username or label without re-entering it.

Note

Leaving the password blank has one side effect worth knowing: API version detection only runs when a password is supplied. An edit that keeps the stored password keeps the previously detected version too. Use Test connection if you want detection to run again.

API version detection

SmartZone’s API is versioned in the URL path, and controllers differ. Rather than asking you which version yours speaks, SZ-MCP detects it.

On Save & detect, it tries these versions in order and keeps the first that accepts a login:

v14_1, v14_0, v13_1, v13_0, v12_1, v12_0,
v11_1, v11_0, v10_1, v10_0, v9_1, v9_0

Newest first, so you pin to the most recent version your controller accepts. The detected version is stored and used for every subsequent call, on both the wifi and switches namespaces.

When probing stops

Detection does not walk the whole list on every failure. It continues to the next candidate only when the controller answers 404 or 405 — the signals that this particular version path does not exist.

Anything else stops the loop immediately: rejected credentials, an unreachable host, a timeout, a TLS failure, a refused host. Continuing would just replay your password against a controller that has already answered, so the first meaningful error is the one you get back.

Caution

This is why a wrong password produces one clear login_failed rather than twelve login attempts. If your SmartZone locks accounts after repeated failures, a single bad save costs you one attempt, not twelve.

Testing, rotating and deleting

Test connection

Test connection flushes the cached service ticket, decrypts the stored password, and re-runs detection against the saved credentials. If it finds a different version than the one stored, it updates the stored one.

On success the dashboard shows Connection OK — API version v13_1 and stamps the last-verified time (shown in UTC).

A failed test is reported inside a success

The test endpoint answers HTTP 200 even when the test fails, carrying { "ok": false, "error": "..." } in the body. The dashboard reads the ok field and renders Test failed: …, so the UI is correct — but anything calling the API directly must inspect ok rather than the status code.

Rotating the SmartZone password

Change it in SmartZone, then paste the new password into the dashboard and save. The cached service ticket is flushed on every save, so the next call mints a fresh one with the new password — you do not need to reconnect Claude.

Deleting

Delete removes the stored credentials and flushes the cached ticket. Your Claude connector stays registered but stops working: call returns no_credentials with the message “No SmartZone credentials configured for this account. Sign in at the dashboard and save SZ credentials.”

To revoke Claude’s access rather than the controller’s, see Connecting to Claude.

Error codes on save and test

Code	Meaning
forbidden_host	The host is not publicly routable — see Controller requirements
invalid_host	The controller could not be reached: DNS failure, refused connection, timeout, or a TLS certificate that failed validation
login_failed	The controller answered but rejected the login. Carries the upstream status, for example http_401
no_credentials	Nothing is saved for this account yet
decryption_failed	The stored ciphertext could not be decrypted. Re-enter the password

If Save & detect keeps failing with a username and password you know are right, the error is invalid_host, not login_failed: SZ-MCP never reached the login. The usual cause is the controller’s self-signed TLS certificate. See Controller requirements.

The detail returned for login_failed is deliberately terse. SmartZone’s own error bodies can disclose account-lockout state and username hints, so they are logged server-side and not echoed back.

Next steps

Connecting to Claude Add the connector, and manage the OAuth tokens that bind it to your account.

Controller requirements The certificate and addressing rules a save has to satisfy.

Security model How the password is encrypted, and when it is decrypted.

Troubleshooting Working back from an error code to the layer that produced it.