GuilduoReference GUILDUO
Guilduo troubleshooting: connections, scopes and saving
First identify whether the failure is endpoint access, OAuth, Agent linking, discovery, permissions or persistence. Inspect the failed read and error before changing connection settings.
401, OAuth callback and account mismatches
A 401 on an unauthenticated protected MCP or REST route can be expected. Opening a URL in a browser alone does not verify a client connection.
- Check that the MCP URL is https://mcp.guilduo.com/mcp. https://api.guilduo.com/v1 is the Appwrite API.
- Verify that the Web App and OAuth flow use the same account. You may be reading another account's workspace.
- Re-authorize OAuth if an old migration-era connection or expired grant is the cause. Do not reuse old grants or tokens.
- If OAuth does not return, inspect extensions blocking the callback and the client's return state.
Tools or Skills are missing
The /health tool count and actual authenticated client tools are separate checks. Do not expand Agent scopes solely because counts differ.
- Identify the required tools. Human Relay needs request_human_review and list_human_requests.
- Refresh connection metadata, then restart and begin a new chat if needed.
- Check Skill loading separately. An installed Codex companion is not necessarily loaded into an already running conversation.
- If Refresh fails, record the client version, exposed tools and error. Do not immediately remove a working connection or create duplicates.
Unlinked, read-only and 403 failures
| Symptom | Value to inspect | Action |
|---|---|---|
| linked=false / agent=null | Connections link | Link the intended Agent and reread context |
| Missing agents:read | connectionScopes | Review OAuth consent |
| Relinking refused | OAuth agents:write | Check connection control permission |
| Quest writes alone fail | quests:write in both policies | Allow the necessary scope on the missing side |
| Human answer refused | Authenticated human Web session | The human must answer in the Web App |
409, retries and uncertain save results
- quest_conflict: reread the Quest and preview with the current expectedUpdatedAt.
- Handoff conflict: read the actual state and refresh expectedState. Do not revert accepted work using an old state.
- request_key_conflict: different request content reused the same key. Inspect the existing request and use a new key for a new round.
- human_request_pending: resume the pending or deferred request. Do not create a duplicate under another key.
- Lost save response or 5xx: read the state first. General Quest creation is not made idempotent by a Human request key; decide on a retry after inspecting persistence.
Reconnect and report the issue
Previous data can remain read-only during synchronization. Reconnect with the same account and verify saved state. Check Archive after completing a one-off To Do.
Public GitHub Issues are at https://github.com/ELRdn/Guilduo/issues. Include the following to help distinguish authentication, UI and tool-contract issues.
- Client name and version, time, expected behavior and actual result.
- Failed tool or REST path, HTTP status and error code.
- Whether reading, previewing or saving failed, and the state observed on reread.
- A minimal reproduction without credentials or Quest content. Do not publish tokens, complete UIDs or Client IDs.
Sources for this article
Edited from the public GitHub documentation. Read the original sources for specification details.
Content reviewed: · Public source revision: 5125178