Troubleshooting
Start with the server URL, selected workspace and client connection status. Restart a failed OAuth flow from the client instead of reusing an old authorization URL or consent tab.
Production: https://mcp.upty.io/mcp
Development: https://mcp.uptiva.linuxmaster.cloud/mcp
Sign-in and connection errors
| Symptom or message | What to do |
|---|---|
Opening the URL shows MCP authentication required | It is a protocol endpoint, not a dashboard. Add it through an OAuth-capable MCP client to start discovery and sign-in. |
| No eligible workspace / no MCP access | The workspace needs monitoring access and API access on its plan. Check current membership and role for shared workspaces. |
| Consent expired or authorization request changed | Restart from the client. Consent is time-limited and tied to the original account and parameters. |
invalid_client | Start a new connection. The client must supply valid metadata or register its callback. Do not invent a client ID. |
| Callback or return-address error | Use the URI generated by the client; see loopback guidance below. |
| Invalid/expired access token (401) | Let the client refresh. Reconnect if refresh fails or the connection was revoked or expired. |
| An app stops working | Check Connected apps, expiry, account status, membership, role and plan. Credential/session revocation may require reconnecting. |
| Too many requests (429) | Pause retries, reduce frequency and resolve repeated sign-in failures. One prompt can cause several requests. |
Loopback callback or redirect errors
Claude Code and other native clients may choose a new temporary callback port on each login. Upty permits dynamic ports for registered HTTP loopback callbacks on exactly localhost, 127.0.0.1 or [::1].
Those hosts are not interchangeable. The exception does not permit another callback path or query. HTTPS callbacks, private LAN hosts and other addresses still need the registered match. Token exchange must use the same redirect URI used by that authorization request.
If a saved connection fails with an old callback:
- Restart authentication from the client's MCP settings or
/mcpcommand. - Let the client generate its new request and temporary callback.
- Do not replace the host, edit the port manually or alter the returned code URL.
- If it still fails, report the client version and redacted error, never the code or token.
Upty supports OAuth client metadata discovery and dynamic registration for compatible clients. A working general endpoint does not establish certification for every client release.
Full access is unavailable or only read tools appear
Two independent checks apply:
- Client request: the original authorization request must include management scope (
mcp:write) for Full access to be offered. - Workspace role: a view-only role cannot authorize management. Some operations also require permission over the whole workspace rather than selected monitors.
Upty initially selects Read-only even when Full access is available. If you approved Read-only, disconnect and authorize a new connection with the intended scope. Codex's explicit scope command is in Connect your assistant.
The assistant cannot repair its own permissions. Role and plan changes stay in the dashboard or another separately authorized workflow.
Tool and data errors
| Symptom | What to check |
|---|---|
| Tool missing | Tool discovery is filtered by approved scope and current role. Compare the catalogue with connection and membership settings. |
| Permission or plan error (403) | Check workspace, ownership, role, feature and quota. Repeating the unchanged operation cannot grant access. |
| Resource not found (404) | Resolve its real UUID through this connection's read tools. Another workspace's ID does not grant access. |
| Invalid arguments | Follow the advertised schema: placeholders, unsupported enum values and arbitrary fields are not valid input. |
| Monitor update would overwrite settings | Use update_monitor with only intended partial fields. Do not replace credentials with a redacted read result. |
| Maintenance update rejected | Include current monitor_ids, title, start and valid end/recurrence settings. Read the window before replacing it. |
| Status-page update rejected | Explicitly provide data.title, data.enabled and data.monitor_ids, preserving them unless changing them deliberately. |
| Deletion preparation expired, missing or already used | Prepare again, review the same target and obtain appropriate approval before confirming. |
| Confirmation name mismatch | Use the exact returned name for the approved resource, not a similar guessed name. |
| Monitoring backend unavailable | This may be a temporary Upty-to-backend problem. Retry later and report a persistent failure with a redacted error. |
| Fewer resources than expected | Check workspace scope, monitor-scoped permissions, pagination and bounded lists. Missing data does not prove health or absence. |
Inspect the client
Claude Code's /mcp shows servers and authentication state. If using the plugin, confirm upty@upty is installed and restart when requested. Avoid unintentionally adding the plugin and a duplicate direct server entry.
In Codex, codex mcp list shows configured servers and codex mcp login upty starts OAuth again. Consult the installed CLI's help or current OpenAI documentation for version-specific controls.
For other clients, use their MCP settings and logs. A client limited to fixed bearer headers cannot complete this consent flow by pasting an ordinary Upty REST API key.
Ask for help
Open Upty Support with the client/version, production or development endpoint, failed tool or connection step, status, redacted error and approximate time. Say whether a fresh OAuth attempt changed the result.
Exclude passwords, authorization codes, access/refresh tokens, private heartbeat URLs, host credentials and channel secrets. Do not attach an unredacted callback URL or configuration file.