# MCP tools

<!-- Generated by scripts/docs/generate.ts. Do not edit by hand. -->

The MCP endpoint exposes a curated set of 15 tools.
Every tool is scoped. `tools/list` returns only the tools the presented API key
or OAuth grant can invoke.

| Tool                   | Scope          | What it does                                                                                                                                                                                                                                                                                                                                                                                 |
| ---------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_decks`           | `decks:read`   | List compact deck summaries.                                                                                                                                                                                                                                                                                                                                                                 |
| `get_deck`             | `decks:read`   | Read deck metadata and, optionally, compact cards.                                                                                                                                                                                                                                                                                                                                           |
| `search_cards`         | `decks:read`   | Search and filter cards across decks.                                                                                                                                                                                                                                                                                                                                                        |
| `get_card`             | `decks:read`   | Read one card in full.                                                                                                                                                                                                                                                                                                                                                                       |
| `get_learning_stats`   | `stats:read`   | Read accuracy, due counts, and weak cards for a deck.                                                                                                                                                                                                                                                                                                                                        |
| `get_study_plan`       | `stats:read`   | Request a Clef-informed (with scheduler fallback) study plan. Pick the practice style with `mode` (flashcards, multiple_choice, typed, matching, cloze, mixed) and the intent with `goal`; `goal: "cram"` covers every active card regardless of schedule.                                                                                                                                   |
| `create_deck`          | `decks:write`  | Create a deck. Pass `collectionId` (from a collection the caller owns) to file it under a collection.                                                                                                                                                                                                                                                                                        |
| `create_cards`         | `decks:write`  | Bulk-create up to 100 cards in a deck. A deck holds at most 500 live cards; a call that would exceed the cap fails with the stable code DECK_CARD_LIMIT_EXCEEDED.                                                                                                                                                                                                                            |
| `import_deck`          | `decks:write`  | Import cards from CSV, TSV, or JSON (at most 500 rows per call). The deck is capped at 500 live cards, so split larger imports across decks or delete cards first; an import that would exceed the cap is rejected as a whole with DECK_CARD_LIMIT_EXCEEDED.                                                                                                                                 |
| `update_card`          | `decks:write`  | Update one card.                                                                                                                                                                                                                                                                                                                                                                             |
| `delete_card`          | `decks:write`  | Soft-delete a card.                                                                                                                                                                                                                                                                                                                                                                          |
| `start_study_session`  | `study:write`  | Start a study session without UI. `mode` supports flashcards, multiple_choice, typed, matching, cloze, and mixed; `goal` supports learn, review, cram, retain, and diagnose. Use `goal: "cram"` to revise every active card and `mode: "matching"` for pair matching. When the user wants to study in chat, call `render_study_session` once instead of this tool followed by a render call. |
| `record_review`        | `study:write`  | Append a review result to a session.                                                                                                                                                                                                                                                                                                                                                         |
| `get_study_session`    | `decks:read`   | Fetch the current authoritative study-session snapshot (no UI).                                                                                                                                                                                                                                                                                                                              |
| `render_study_session` | `study:render` | Render an interactive study session as the MCP Apps widget: pass `deckId` to start a session (plus optional `mode`, `goal`, `minutes`) or `sessionId` to resume one. Call this as the only tool in the turn — mobile ChatGPT clients do not render a widget whose tool follows another tool call, so do not call `start_study_session` first.                                                |

## Tool to scope

| Tool                   | Scope          |
| ---------------------- | -------------- |
| `list_decks`           | `decks:read`   |
| `get_deck`             | `decks:read`   |
| `search_cards`         | `decks:read`   |
| `get_card`             | `decks:read`   |
| `get_learning_stats`   | `stats:read`   |
| `get_study_plan`       | `stats:read`   |
| `create_deck`          | `decks:write`  |
| `create_cards`         | `decks:write`  |
| `import_deck`          | `decks:write`  |
| `update_card`          | `decks:write`  |
| `delete_card`          | `decks:write`  |
| `start_study_session`  | `study:write`  |
| `record_review`        | `study:write`  |
| `get_study_session`    | `decks:read`   |
| `render_study_session` | `study:render` |

Scopes are defined in `packages/shared/src/api/mcp.ts`. The same file drives the
server’s `tools/list` and the web app’s MCP settings screen.

## Schemas

Call `tools/list` against a running instance to receive the live JSON Schema for
each tool. The schemas are inferred from the Zod contracts in
`packages/shared/src/api/mcp.ts`; this page intentionally does not duplicate
them, so it cannot drift.

## Audit

Every mutating tool writes a row to `mcp_audit_events`: user, tool, action,
bounded input summary, affected ids, request id, and timestamp. `import_deck`
payloads are truncated before they are stored.