Troubleshooting

Find the server's messages

The server writes its messages to standard error.

• Claude Desktop saves them to ~/Library/Logs/Claude/mcp-server-vsp360.log on macOS, or %APPDATA%\Claude\logs\mcp-server-vsp360.log on Windows.
• From a terminal, start it with your settings to see them directly:

VSP360_URL=https://vsp360.example.com VSP360_CLIENT_ID=my-service-account VSP360_CLIENT_SECRET=REPLACE_ME vsp360-mcp

On a good start you'll see [vsp360-mcp] ready: 264 operations, 0 direct tools, read-only. The server signs in to VSP 360 only when it makes its first request, so this doesn't test your credentials. Press Ctrl+C to stop it.

Common problems

Symptom	Cause and fix
Server doesn't appear in Claude Desktop	Invalid JSON, or the entry is outside mcpServers. Check with python3 -m json.tool <file>, then quit and reopen Claude Desktop.
command not found / ENOENT	Claude Desktop doesn't use your shell's PATH. Use the command's full path (which vsp360-mcp).
ENOENT … ${user_config.ca_cert} (Claude Desktop extension)	An optional setting was left empty, and versions before 0.1.22 read the placeholder as a file path. Update to 0.1.22 or later, or fill in CA certificate and Download folder (#22).
"VSP360_URL uses http://"	Since 0.1.22, plain HTTP needs an opt-in. Use the https:// address, or set VSP360_ALLOW_HTTP=true.
Missing required environment variables	VSP360_URL, VSP360_CLIENT_ID or VSP360_CLIENT_SECRET isn't set for the server. With Docker, each needs -e NAME in args too.
unable to get local issuer certificate	VSP 360's certificate isn't trusted. Set VSP360_CA_CERT to the CA's PEM file, or VSP360_INSECURE_TLS=true on lab systems only.
Token request failed (HTTP 401)	Wrong client ID or secret, or the service account is disabled.
HTTP 403 on a call	The service account lacks permission. vsp360_describe_operation shows the permissions each operation needs.
ENOTFOUND / ECONNREFUSED / timeouts	The machine can't reach VSP 360. Check DNS, proxies and firewalls.
"changes VSP 360 state and the server is running read-only"	Expected. Set VSP360_ALLOW_WRITES=true if you mean to make changes.
"uploads a local file, which read-only mode allows only from VSP360_UPLOAD_DIR"	Set VSP360_UPLOAD_DIR to the folder holding the file.
"Upload refused: … hidden file"	The path is, or is inside, a dot-folder. Move the file, or set VSP360_UPLOAD_DIR.
save_to refused	It must be a file name or a path inside VSP360_DOWNLOAD_DIR (symlinks are resolved), not inside a hidden folder, and mustn't exist yet.
"Redirect refused" / "Token request was redirected"	VSP 360, or something in front of it, redirected to another address. Set VSP360_URL to the address VSP 360 actually answers on.
"is read-only only with action=query"	Read-only mode allows only analytics queries. Other actions need VSP360_ALLOW_WRITES=true.
"larger than VSP360_MAX_RESPONSE_BYTES"	Narrow the request, or save_to a file, which isn't limited.
Response cut off	It exceeded VSP360_MAX_RESPONSE_CHARS. Ask for fewer fields or a narrower filter, or save_to a file.
"Stopped after N pages"	max_pages reached. Ask for more pages, or narrow the request.
Claude picks the wrong operation	Rephrase with API terms, name the area, or add the area to VSP360_TOOLSETS. Low-confidence results tell Claude to compare candidates.

Container-specific problems

See the troubleshooting section of README.docker.md: mount permissions, file paths inside the container, and reaching a VSP 360 on the Docker host.

Still stuck?

Open an issue with the version (npm ls -g vsp360-mcp, or the image tag), how you installed it, and the server's messages. Remove secrets and identifying details first. For security problems, use private reporting instead.