# Troubleshooting

What the client sees, tool error codes, sign-in and consent messages, and the behavior that surprises, each with what to do.

*Where in the portal: Your agent and Settings → Connected apps*

*Last updated: 2026-10-21*

Find the symptom in the table that matches where you see it. If a fix needs an owner or administrator, see [Organization settings for MCP](https://kelrova.com/docs/mcp/organization). To reach Kelrova, see [Getting help](https://kelrova.com/docs/reference/support).

## What the client sees

| Symptom | Cause | What to do |
| --- | --- | --- |
| Every path of `mcp.kelrova.com` answers `404 {"error":"not_found"}` | The MCP server is not available yet. | Try again later. |
| `401` with `WWW-Authenticate: Bearer resource_metadata=…` and no token | Normal first contact: the client has to sign in. | Nothing; the client reads the metadata and starts the browser flow. |
| `401 invalid_token` on a connection that worked | Revoked (by you, an administrator or Kelrova), expired (maximum connection age, machine client expiry, an hour without a refresh token, or 30 days unused), you left the organization, the client was disabled, or the refresh token was used twice. | Reconnect from the client ([Staying connected](https://kelrova.com/docs/mcp/access)). A machine client token lasts 15 minutes and has no refresh token: request a new one. |
| A refresh token worked once, then everything stopped | Two copies of the same client configuration shared one refresh token. The second use is treated as theft and revokes the connection. | Use one configuration per connection and reconnect. |
| `403 {"error":"mcp_disabled"}` | MCP is off for the organization, or its client policy no longer allows this client. | Ask an owner or administrator. |
| `403` with `error="insufficient_scope"` | The tool needs access the connection lacks: `report_finding_action` needs `findings:write`; `request_recheck` needs `findings:recheck`. | Sign in again and grant it. Claude Code needs the access pinned in `oauth.scopes` ([setup](https://kelrova.com/docs/mcp/connect)). |
| `429 {"error":"rate_limited"}` with `Retry-After` | Request limits for the connection or the organization. | Wait for `Retry-After` seconds. |
| `400 invalid_request` | The request is not a valid MCP request. | Use a standard MCP client. |
| `405` on `GET /mcp` or `DELETE /mcp` | The server answers only `POST /mcp`. | Nothing; clients handle it. |

## Tool errors

Tool errors come back with `isError: true` and a body `{"error":{"code","message"}}`. The message is always generic text.

| Code | Meaning | What to do |
| --- | --- | --- |
| `invalid_argument` | An argument is missing, malformed or out of range; `field` names it. | Fix the argument. |
| `not_found` | No such object, or it is outside the connection's projects or your visibility. Retired finding IDs that start with `sdf_` always land here. | Check the ID and the connection's project scope. |
| `forbidden` | The object is visible but your access lacks the action. | Ask a project administrator. |
| `write_disabled` | The organization turned off reports. | Ask an owner or administrator. |
| `recheck_disabled` | The organization turned off re-checks. | Ask an owner or administrator. |
| `proposal_pending` | Another proposal waits for a project member. Your report is kept as a note. | Wait for the member's decision. |
| `finding_busy` | The finding already has a run in progress. | Retry when it finishes. |
| `plan_inactive` | The organization's plan or payment state does not allow a re-check. | Choose or renew a plan. |
| `usage_exhausted` | The usage allowance or queue does not allow a re-check now. | Wait for the next period or top up. |
| `rate_limited` | A rate limit or the re-check budget is exhausted. `retryAfterSeconds` says when to retry. | Wait. |
| `unavailable` | Kelrova could not complete the request. | Retry later; contact Kelrova if it persists. |

## Sign-in and consent

| Symptom | Cause | What to do |
| --- | --- | --- |
| **None of your organizations can connect this app** | MCP is not on for any organization you belong to, or your organizations' policy does not allow the client. | An owner or administrator checks the **MCP server** page: the switch, **Which apps can connect** and the plan. |
| "This organization cannot connect this app" or "This app is not allowed for the chosen organization" after **Allow access** | The organization you chose has MCP off, or its policy no longer allows this app. | Choose another organization, or ask an owner to allow the app. |
| "Too many attempts. Please wait a moment and try again." | Too many attempts in a short time. | Wait a minute and try again. |
| **Unverified app** | The client registered itself, so Kelrova cannot say who runs it. | Approve only clients you started yourself just now. |
| **This app isn't recognised** | The client's published details could not be fetched or are not valid. | Return to the app and try again; if it persists the client is not compatible. |
| **This app can't be connected** | The address the app wants to return to is not registered for it, or it registers in a way Kelrova does not accept. Kelrova never sends you to an unregistered address. | Use the client's supported setup; report a client that always fails. |
| **Something's wrong with this request** | The app sent a request Kelrova could not understand. | Return to the app and try again. |
| **This request has expired** | The consent request is older than 10 minutes. | Start the connection again from the client. |
| **This request was already answered** | The request was already decided, for example by a double click. | Return to the app: it should already be connected or show what happened. |
| **This request was not found** | The link is missing or no longer valid. | Start the connection again from the client. |
| **Couldn't load this request** or **Couldn't complete this connection** | Kelrova could not complete the request. | Retry later. |

## Behavior that surprises

- **The agent asks me to sign in again every hour.** The client did not ask for **Stay connected**. See [Staying connected](https://kelrova.com/docs/mcp/access).
- **The portal shows the connection but the agent has no tools.** The access token expired and the client did not refresh; reconnect.

For a `fixed` report that reopened or did not change a finding, see [What a report does](https://kelrova.com/docs/mcp/reports). For a missing project or a re-check that sees old code, see [A typical run](https://kelrova.com/docs/mcp/loop). Token request errors are on [Machine clients for CI](https://kelrova.com/docs/mcp/machine-clients).

## Related

- [Access levels and staying connected](https://kelrova.com/docs/mcp/access)
- [Organization settings for MCP](https://kelrova.com/docs/mcp/organization)
- [Connect a client](https://kelrova.com/docs/mcp/connect)
- [Getting help](https://kelrova.com/docs/reference/support)