# Troubleshooting

Source: https://www.supervisible.com/developers/mcp/troubleshooting

Resolve connection, permission, preview and rate-limit problems without duplicating changes.


Start with the exact error and the connection's workspace. Do not include tokens, passwords or private record contents in a support request.

| Symptom                                         | Next step                                                                                                                                                                                                                           |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Supervisible is missing from the tool list      | Confirm the saved server URL, enable the connection for this conversation and complete OAuth. Check your client's custom-connector policy.                                                                                          |
| OAuth parameters must not be repeated           | Configure only the base MCP URL, without manually appended OAuth query parameters. Update your client and start a new login. If it persists, report the client version and time of failure; do not edit a signed authorization URL. |
| Login succeeds but requests return unauthorized | Reconnect the saved server. Check that the membership is still active and the connection has not been revoked.                                                                                                                      |
| The connection uses the wrong workspace         | Run `whoami`. Create or reconnect a separate connection and select the intended workspace during consent. Switching workspaces in the app does not switch the grant.                                                                |
| `forbidden`                                     | Check the connected member's current permissions for this action and record. Refreshing OAuth does not grant new privileges.                                                                                                        |
| `not_found`                                     | Resolve the name or ID within the connected workspace. The record may be missing or unavailable to that member.                                                                                                                     |
| A name matches several people or projects       | Select the intended candidate and use its exact ID. Nothing should be applied while the match is ambiguous.                                                                                                                         |
| A preview reports a conflict or stale revision  | Read the current record, preview again, review the changes and use the new revision to apply.                                                                                                                                       |
| HTTP `429`                                      | Wait for the `Retry-After` interval. The MCP limit is shared across tokens for the same workspace membership and OAuth client.                                                                                                      |
| A write times out                               | Read the record before retrying. The write may have committed even if its response was lost.                                                                                                                                        |
| An import is partly successful                  | Inspect the row results and `get_import_jobs`. Correct and retry failed rows rather than blindly resubmitting the whole import.                                                                                                     |
| Financial fields are absent                     | Confirm financial visibility for this member and project. An omitted cost is not zero.                                                                                                                                              |

## Local server cannot connect

A locally running client such as Codex CLI or Claude Code can connect directly to a server on the same machine. Hosted clients need a network-reachable endpoint; their `localhost` is not your laptop. Follow [local testing](https://www.supervisible.com/developers/mcp/local-testing.md) before adding a tunnel.

## Request help

Send [support](mailto:help@supervisible.com) the client name/version, timestamp and timezone, tool name, error code and whether the call was a preview or apply. Include a request ID if one was returned. Redact credentials and sensitive values. For an uncertain mutation, say whether you have checked the current record.