Troubleshooting

Symptom	Likely cause	Resolution
isError: true with "User validation"	Token not assigned to the target workspace	Verify that the API key or the User are assigned and active in the Shared space and workspace.
Auth returns 401	Invalid or expired token	Regenerate the API Access Key token.
Client does not show the MCP tools	Client config not saved / not restarted	Save config file and fully restart the client.
OAuth: /authentication/oauth/authorize returns 404	OAuth server not enabled	Set OAUTH_AUTHORIZATION_SERVER_ENABLED=true
OAuth: authorization rejected with "unknown client"	Client not registered	Add the client entry to OAUTH_AUTHORIZATION_SERVER_CLIENTS site parameter.
OAuth: authorization rejected with "invalid redirect_uri"	Redirect URI not in registered list	Add the exact URI to the client's redirect_uris array in OAUTH_AUTHORIZATION_SERVER_CLIENTS
OAuth: token refresh fails after 30 days	Refresh token expired	User must re-authenticate via browser (re-run OAuth flow).