Troubleshooting

Work from the error you were given. Most failures belong to one of four layers: the certificate, the address, the SmartZone credentials, or the connector.

Save & detect fails

”Test failed: invalid_host”

The controller could not be reached at all. In order of likelihood:

1. The certificate is self-signed. This is the most common cause by a wide margin. The TLS handshake fails before SmartZone sees your username, so the error names the connection rather than the credentials. Install a publicly trusted certificate — see Controller requirements.
2. The certificate does not match the hostname you entered. A certificate for sz.example.com does not satisfy a connection made to an IP address.
3. The port is wrong or closed. Default is 8443; it must be reachable from the public internet.
4. DNS does not resolve, or resolves somewhere unreachable.
5. The controller did not answer within 15 seconds.

Caution

If you are confident the username and password are correct, suspect the certificate before suspecting anything else. A self-signed controller produces a connection error that reads like a configuration mistake.

”Test failed: forbidden_host”

The address you entered is not publicly routable, and SZ-MCP refuses it before making any request. The detail names the reason — for example IPv4 10.1.2.3 is in a reserved/private range.

Private, loopback, link-local, CGNAT and multicast ranges are all refused, as are hosts ending .local, .internal or .localhost, and non-canonical IP literals such as 2130706433 or 127.1. The full list is in Controller requirements.

There is no tunnel or agent component. A controller on a private LAN has to be published before SZ-MCP can reach it.

”Test failed: login_failed”

The controller answered and rejected the login. The detail carries the upstream status, such as http_401.

Check the username and password against the SmartZone admin UI. The detail is deliberately terse — SmartZone’s own error bodies can disclose account-lockout state, so they are logged server-side rather than returned.

One bad save is one login attempt, not twelve

Version detection walks a list of twelve API versions, but it only advances on a 404 or 405 — the signals that a version path does not exist. A rejected credential stops the loop immediately, so a wrong password costs a single attempt against any lockout policy you have configured.

”host must be a bare FQDN or IP (no scheme, no path)”

The Host field takes sz.example.com, not https://sz.example.com and not sz.example.com/wsg. Remove the scheme and any path. The port goes in its own field.

The save succeeded but no version was detected

Version detection only runs when a password is supplied. If you edited the host or username and left the password blank, the previously detected version was kept. Click Test connection to force detection to run again.

A test that reports failure with a green status

The credentials test endpoint answers HTTP 200 even when the test fails, carrying { "ok": false, "error": "…" } in the body. The dashboard reads ok and renders the failure correctly, so you will see it in the UI — but anything scripting the API directly must check ok rather than the status code.

The same principle applies inside code mode: call returns HTTP failures as values with ok: false rather than throwing. See Code mode primitives.

The connector will not authorize

Claude loops through sign-in without reaching consent

Your session cookie is not surviving the redirect back from Google. Sign in at sz-mcp.lanpulse.com first, confirm the dashboard loads, then add the connector in Claude — the consent screen reuses that session rather than starting a fresh sign-in.

If it persists, remove the connector in Claude and add it again, so Claude re-registers from a clean state.

”Please accept the Terms and Privacy Policy to continue.”

The consent screen requires the terms checkbox on your first authorization. Tick it and choose Allow again.

The connector is authorized but Claude sees no tools

tools/list returns exactly one tool, code_mode. If Claude reports none, the bearer token is not being accepted — remove and re-add the connector.

”rate_limited” when adding the connector

Client registration is capped at 20 per IP per hour. Normal use registers once, so hitting this means something is re-registering in a loop. Wait an hour, then add the connector once and let it complete.

Errors from inside code mode

”No SmartZone credentials configured for this account”

call returned no_credentials. The connector is authorized but no controller is saved — or it was deleted. Save credentials on the dashboard; no reconnect is needed afterwards.

”code_mode exceeded 20000ms wallclock budget”

The program ran past its 20-second budget. It is usually an unbounded pagination loop. Ask for the work in smaller pieces — each code_mode call gets a fresh budget. See Limits and quotas.

”code must be under 20,000 characters”

The generated program exceeded the source limit. Ask for a narrower task.

Repeated 401s from the controller

A 401 triggers one automatic ticket refresh and retry. A second 401 is returned as-is, which means the credentials are being rejected at login, not that the ticket expired. Run Test connection to confirm, and check whether the SmartZone password changed or the account was locked.

A 404 on an endpoint that discovery found

The bundled endpoint catalogue describes a v13_1 controller. If yours runs an older version, an endpoint in the index may not exist on it. This surfaces as a 404 from call rather than as a discovery failure. See The two API surfaces.

A program that calls list_tag_groups fails

list_tag_groups no longer exists on either namespace. It was removed because the SmartZone specs define no tag groups, so it only ever returned an empty list. The group argument on list_tags went with it. Start discovery with list_tags(), which takes no arguments. See Finding the right endpoint.

get_endpoint_details shows requestBody: null on a POST

Also expected. The specs are Swagger 2.0, where a request body is a parameters entry with in: "body". The hasBody flag on index entries is false for the same reason. Read parameters instead — see Code mode primitives.

Everything worked yesterday and fails today

Symptom	Likely cause
Sudden login_failed	The SmartZone password changed, or the account was locked or disabled
Sudden invalid_host	The controller’s certificate expired, or DNS/port changed
403 on calls that used to succeed	The SmartZone account’s role or domain scope was narrowed
Connector stopped working entirely	Credentials were deleted on the dashboard, or the connector was removed in Claude

Still stuck

Contact support.neuralconfig.com. Include the exact error text, whether it came from the dashboard or from Claude, and your controller’s SmartZone version.

Never send your SmartZone password.

Next steps

Controller requirements The certificate and addressing rules behind most first-time failures.

SmartZone credentials Every save and test error code, and what each one means.

Limits and quotas The budget or cap behind a given error message.

Connecting to Claude Re-adding the connector, and what the tokens do.