Guilduo API and MCP reference: endpoints and examples

Distinguish REST, MCP and Appwrite

Use /mcp for normal MCP connections. /mcp-next is a validation lane. Do not redirect Worker Quest routes to the Appwrite API.

Check authentication and schemas

Ordinary MCP users use OAuth. OpenAPI defines OAuth and Appwrite JWT Bearer authentication. Fixed API-key distribution is not the normal user flow.

api/openapi.json defines REST paths, inputs and responses; api/mcp-tools.json defines tool names and schemas. Check required fields, enums and length limits before calling.

Tool discovery does not replace authentication or Agent policy. Read identity and effective scopes with get_current_agent_context, then read the target's current state.

Read the Quest list

The following input reads list_quests. Inspect quests, total and nextCursor. If nextCursor is present, pass it as cursor in the next call.

1. Connect OAuth MCP and verify the intended Agent and required quests:read with get_current_agent_context.
2. Call list_quests with the input above and compare it with Backlog in the Web App.
3. Pass an actual returned ID to get_quest as questId and read details and updatedAt. Do not infer IDs from display names.
4. For REST, use an authenticated GET /v1/quests?view=backlog&kind=todo&limit=5. Do not confuse an unauthenticated 401 with a storage or network failure.

{
  "view": "backlog",
  "kind": "todo",
  "limit": 5
}

Map operations to tools and REST routes

The CLI is a REST client for people and CI. Writes execute when --execute is supplied. CLI usage and OAuth MCP discovery are distinct interfaces.

Understand writes and error contracts

• Execute assign_quest_to_agent and request_human_review after preview with the current expectedUpdatedAt. transition_quest_handoff uses expectedState.
• Do not add undefined dryRun fields to create_quest or update_quest. Tools with additionalProperties=false reject undefined properties.
• For 401 inspect authentication; for 403 permissions and identity; for 409 conflicts. requestKey retries the same Human review round and is not a general Quest-creation retry guarantee.
• On conflict, read current state and preview again. Do not repeatedly resend stale timestamps or fabricate a Human answer through general updates.
• Tool counts and versions change. Compare the connected tools/list with the published contract and verify compatibility by required names and schemas.