Check the entry your client actually uses
mcpbridge doctor --profile work --client ci_exampleThe profile and ID must match your client configuration. Omit --client to check login alone. The default timeout is 15 seconds; add --timeout 30s for a slow network. The allowed range is 1 second to 2 minutes.
Diagnostics check the private directory, login renewal, pairing, the live authorization, effective scopes, personal accounts, MCP initialization, and the first page of the tool catalog. They may refresh your MCPHub login token. They do not open a browser, start the Broker, create an authorization, refresh upstream credentials, or execute tools.
Success or warnings only return exit code 0; a blocking problem returns 1. A successful check does not guarantee that every business call or permission will work.
Command not found or client cannot start
Run setup --help. If the command is unavailable, use its absolute path and check the CPU architecture and execution permissions. If it works in a terminal but fails in your client, check that command points to an existing file, Windows uses the exe file, and env.MCPHUB_HOME is preserved.
Login and browser authorization
| Symptom | Action |
|---|---|
| The browser does not open | Open the terminal's authorization link on the same computer. |
| Timeout or callback failure | Retry login and check the fixed callback port and where the command runs. |
| Pending or disabled user | Ask your administrator to enable your user and service access, then log in again. |
| Expired link or wrong account | Check the portal user, send a new request from the terminal, and verify the new pairing code. |
No tools are available
- Check your company account and target service.
- Check that the authorization includes the required tools and scopes.
- Ask your administrator to check publication and access permissions.
- Authorize again when you need newly added tools.
If the wizard cannot discover the catalog, ask your administrator to check the version and settings. Older deployments may require a manual authorization under their guidance.
Authorization expired, revoked, or changed
mcpbridge client authorize --profile work --client ci_exampleConfirm in the browser, then reconnect the client. A valid login does not replace entry authorization. If an upstream account was replaced or disconnected, restore the account first, then authorize again.
Personal account problems
Connect or reconnect the service from Connected accounts in the portal. Contact your administrator if verification keeps failing. If the account is connected but a business operation is denied, check the upstream role and resource permissions.
401, 403, 429, and 503
| Error | Check first | Next step |
|---|---|---|
| 401 | Login and renewal. | Run login --profile work, then reconnect. |
| 403 | User status, scopes, tools, resources, and authorization. | Read the diagnostic report and ask your administrator to confirm the required access. |
| 429 | Rate and concurrency limits. | Wait for capacity; for a write, first verify whether it was already accepted. |
| 503 or persistent unavailability | Gateway, identity provider, account service, and backend. | Save diagnostics and request IDs for your administrator. |
Approved, but not executed
Check the required number of reviewers, the original authorization's expiry, and whether the original client called mcphub_resume_approval. Query the status and follow any expiry, resource, or policy change instructions. You cannot use a different entry to execute the approval.
Still blocked
Follow Contact support to collect the time, entry, service, and request ID. Avoid repeatedly broadening permissions or replaying writes while troubleshooting.