MCP tools
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.