MCP Reference

TaskRatchet runs a remote MCP (Model Context Protocol) server so any MCP-capable client — Claude Desktop, ChatGPT, or your own — can operate a user's account as a set of callable tools instead of prose instructions. It authenticates with OAuth, not personal API keys.

Just want to connect an existing client, not build one? See Connect an AI Agent instead.

Connect

• Server URL: https://api.taskratchet.com/mcp (Streamable HTTP transport)
• Discovery manifest: GET /server-card.json (also reachable via GET /.well-known/mcp, which redirects there). It lists the live tool set — treat it, not this page, as the source of truth if the two ever disagree.

Every request needs a bearer OAuth access token; see the OAuth Reference for how to get one and which scope each tool below needs.

Tools

Tool	Scope	Does
list_tasks	tasks:read	List the caller's tasks, newest due first
get_task	tasks:read	Get one task by id
complete_task	tasks:complete	Mark a task complete
preview_mark_incomplete	tasks:complete	Preview un-completing a task
preview_uncle_task	tasks:uncle	Preview giving up on a task early — starts its charge once confirmed; only once per task
preview_edit_task	tasks:write	Preview editing a task's deadline or stake (only allowed to get harder)
preview_create_task	tasks:write	Preview creating a new task with a stake
confirm_action	scope of the previewed action	Execute the action described by a preview_* tool's confirmation token

Preview/confirm pattern

Anything that affects money — creating, editing, un-completing, or giving up on a task — is two-step:

1. Call the matching preview_* tool. It validates the request and returns a confirmation_token describing exactly what will happen.
2. Show that to the user, and once they agree, call confirm_action with the token to actually do it.

Tokens are single-use and expire after 5 minutes. list_tasks, get_task, and complete_task are single-step, not preview-gated — they're read-only or risk-reducing only, so there's nothing to confirm.

Every client is expected to surface the preview to the user rather than auto-confirming. TaskRatchet has no way to enforce that from the server side, though — the two-call split only guarantees a client could show the user before committing, not that it does. A client that calls preview_* then confirm_action back-to-back is indistinguishable, from the server's perspective, from one that waited for real approval.