# MCP Reference

TaskRatchet runs a remote [MCP](https://modelcontextprotocol.io) (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](/oauth), not personal API keys.

Just want to connect an existing client, not build one? See [Connect an AI Agent](/agents) 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](/oauth) 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.