Errors and troubleshooting
Diagnose REST authentication, authorization, validation, rate-limit, workspace, and MCP connectivity failures.
Authentication failures
For a REST 401 or MCP unauthorized response:
- confirm the header uses
Authorization: Bearer ... - confirm the entire one-time key was copied
- remove extra quotes or whitespace introduced by a secret store
- check the key remains active under Settings → MCP & API
- create a replacement if the original full value was lost
Do not print the token to logs while diagnosing it.
Missing scope or role
An MCP tool error names the missing scope when the key cannot perform an action. Employee and secret configuration also require an owner or admin role. A key created by a user who was later demoted cannot bypass the new role.
The current settings screen creates keys with all three scopes. Use a separate client-specific key, keep manager membership narrow, invoke only the required tools, and revoke the client key when its job ends.
Wrong workspace
Keys are bound at creation. Revoke the key, switch to the intended workspace in the Yodu app, and generate a new key. Do not look for an organization argument to override the binding.
Rate limiting
REST returns 429 and the MCP endpoint returns a rate-limit error when a key sends too many requests. Respect the Retry-After header, add exponential backoff with jitter, cache safe reads, and avoid polling runtime state aggressively.
Validation errors
Use the interactive API reference for REST schemas and the client's discovered tool schema for MCP inputs. Validate enum values, maximum lengths, required IDs, and URL formats before a request.
MCP client shows no tools
- Confirm the URL is
https://app.yodu.ai/api/mcp. - Select Streamable HTTP rather than
stdio. - Confirm the client supports custom authorization headers.
- Restart clients that load MCP configuration only at startup.
- Check whether a proxy strips the authorization header.
- Recreate the connection with a new client-specific key.
An operation is absent
The public surfaces are curated allowlists. If a route or tool is not present in the REST endpoint map or MCP tool inventory, use the Yodu app. Do not depend on private application procedures.