MCP reference
MCP, the Model Context Protocol, lets a compatible AI client read your learning context from Vocapi. It can use that context when you ask for help, instead of asking you to describe your progress each time.
What can it read?
Link to “What can it read?”Vocapi’s MCP tools provide your progress, due reviews, vocabulary knowledge, difficult words, and recent writing errors. They also provide lessons, reading material, and sentences from courses you can access.
The connection is read-only. It cannot submit reviews, change your progress, or mark cards as learned.
MCP uses sign-in approval, separate from personal API keys.
For example, you could ask your connected tutor:
- “Use my Vocapi vocabulary to help me practice words I’m struggling with.”
- “Look at my Vocapi progress and suggest something to review.”
Manage or remove access
Link to “Manage or remove access”Open Settings → MCP connections to see connected tutors and their available last-use information. Select a connection to view its access details or choose Revoke connection.
Existing access can continue for up to one hour after you revoke a connection.
The AI service receives the data requested through the connection. Check that service’s privacy settings and policy for how it handles the data it receives.
11 read-only tools
Start with get_tutoring_briefing for the learner’s current context. Use the other tools to explore a particular part of it.
Names, descriptions, and schemas below come from the registered MCP tools.
TOOL
get_tutoring_briefing
Get a complete, token-lean snapshot of the learner's current state.
Call this FIRST at the start of a tutoring session. It returns, for the learner's active language: where they are in the curriculum (level, XP, next lesson), the words they keep getting wrong and why (leeches with lapse counts), how much vocabulary they hold at each strength band, the review workload due now and forecast for the week, their streak, and a short ordered suggested_focus list of concrete next actions.
The learner is resolved from the authenticated connection -- there is no user parameter. If the active language is locked (subscription required or frozen) the briefing reports the lock and omits per-language detail instead of failing. Do not call the granular tools to reconstruct this picture; this single call already composes them.
Parameters
No parameters.
Result schema
{
"additionalProperties": true,
"type": "object"
}
TOOL
get_curriculum
List the language's curriculum: chapters and lessons in order.
Returns each chapter with its lesson-completion rollup, and a paginated list of lessons in global curriculum order (with lesson id, slug, type, and tier). Use the lesson ids with get_lesson_content to fetch the actual teaching material. lessons.total is the full lesson count for the language. Call get_tutoring_briefing first to know the learner's language and position -- this is a drill-down, not the opening move.
Parameters
languageOptional · string | null-
Optional language code (e.g. 'sw', 'ga'). Defaults to the learner's active language when omitted. A locked or frozen language raises a remediation error.
Default:
null limitOptional · integer-
Max lessons (1-200, default 50).
Default:
50Minimum: 1 · Maximum: 200
offsetOptional · integer-
Lessons to skip for pagination.
Default:
0Minimum: 0
Result schema
{
"additionalProperties": true,
"type": "object"
}
TOOL
get_grammar_summary
Show the learner's mastery of each grammar point in the curriculum.
Each grammar point carries a mastery_score in [0, 1] and a band (none/bronze/silver/gold) derived from FSRS stability and how often the learner has encountered the pattern in reading. Use this to find weak or unlearned structures worth reinforcing, and to avoid re-teaching patterns already at gold.
Parameters
languageOptional · string | null-
Optional language code (e.g. 'sw', 'ga'). Defaults to the learner's active language when omitted. A locked or frozen language raises a remediation error.
Default:
null
Result schema
{
"additionalProperties": true,
"type": "object"
}
TOOL
get_lesson_content
Get one lesson's full compiled content in its sections/beats shape.
Returns the projection of the lesson's STORED compiled build (B5 #1629): contract: "sections" plus ordered sections whose beats carry the resolved text, sentences, grammar and audio URLs. Quote from this instead of paraphrasing. An immersion lesson has no compiled build (its reading is picked dynamically in-app) and refuses loudly. Access is checked against the lesson's language, so a locked language raises a remediation error.
Parameters
lesson_idRequired · string-
The lesson id (from get_curriculum).
Result schema
{
"additionalProperties": true,
"type": "object"
}
TOOL
get_progress
Show the learner's position: XP, level, streak, next lesson, chapters.
Returns XP and level for the language, the global streak (streaks span all languages), the next lesson to continue, and a per-chapter completion rollup. Use this to drill into curriculum position AFTER the briefing -- do not open with it or use it to discover the learner's language or overall state; call get_tutoring_briefing first for that.
Parameters
languageOptional · string | null-
Optional language code (e.g. 'sw', 'ga'). Defaults to the learner's active language when omitted. A locked or frozen language raises a remediation error.
Default:
null
Result schema
{
"additionalProperties": true,
"type": "object"
}
TOOL
get_reader
Get one graded reader with its ordered sections.
A graded reader is a controlled-vocabulary passage sized to the learner's level. Returns the reader's metadata (word count, topic tags, license, attribution) and its ordered sections with body text and audio URLs. Use it to give the learner comprehensible reading practice.
Parameters
reader_idRequired · string-
The graded-reader content-item id.
Result schema
{
"additionalProperties": true,
"type": "object"
}
TOOL
get_recent_errors
Show recurring mistakes from the learner's recent free writing.
Aggregates the most recent graded free-production attempts into error categories (e.g. agreement, tense), each with a count and a few original/correction example pairs. Use this to target the errors the learner actually makes in production, not just SRS misses. Empty when the learner has not done free-writing yet.
Parameters
languageOptional · string | null-
Optional language code (e.g. 'sw', 'ga'). Defaults to the learner's active language when omitted. A locked or frozen language raises a remediation error.
Default:
null windowOptional · integer-
Number of recent free-writes to analyse (default 50).
Default:
50Minimum: 1 · Maximum: 200
Result schema
{
"additionalProperties": true,
"type": "object"
}
TOOL
get_srs_forecast
Show the review workload due today and coming up this week.
Returns a per-day breakdown (vocabulary vs grammar counts) plus total_upcoming across the window. If the language is paused or frozen the forecast is empty with stopped=true -- that is a real state, not an error. Use this to decide whether a session should focus on clearing due reviews before teaching anything new.
Parameters
languageOptional · string | null-
Optional language code (e.g. 'sw', 'ga'). Defaults to the learner's active language when omitted. A locked or frozen language raises a remediation error.
Default:
null
Result schema
{
"additionalProperties": true,
"type": "object"
}
TOOL
get_struggling_words
List the words and grammar points the learner keeps getting wrong.
These are leeches -- items with a high lapse count that the SRS has flagged. Each carries lapse_count (how many times relearned), leech_at, stability, and last_review_at so you can see how entrenched the difficulty is. Worst offenders first. Prioritise these in a session over introducing new material.
Parameters
languageOptional · string | null-
Optional language code (e.g. 'sw', 'ga'). Defaults to the learner's active language when omitted. A locked or frozen language raises a remediation error.
Default:
null limitOptional · integer-
Max struggling words (default 50).
Default:
50Minimum: 1 · Maximum: 200
Result schema
{
"additionalProperties": true,
"type": "object"
}
TOOL
get_vocabulary_knowledge
List the words the learner knows, with per-word FSRS strength.
Each item carries the word, translation, card state, and a strength band derived from FSRS stability: new (never reviewed), learning, known, strong. band_counts rolls up the WHOLE inventory (not just the returned page) so you can gauge the learner's i+1 envelope -- keep new material within reach of what they already hold. Paginate via offset/limit; has_more signals another page. Use this to avoid drilling a learner on words already at strong. Drill-down, not an opener: call get_tutoring_briefing first for the learner's state.
Parameters
languageOptional · string | null-
Optional language code (e.g. 'sw', 'ga'). Defaults to the learner's active language when omitted. A locked or frozen language raises a remediation error.
Default:
null limitOptional · integer-
Max items to return (1-500, default 100).
Default:
100Minimum: 1 · Maximum: 500
offsetOptional · integer-
Items to skip for pagination.
Default:
0Minimum: 0
Result schema
{
"additionalProperties": true,
"type": "object"
}
TOOL
search_sentences
Find example sentences, optionally filtered by grammar point.
Returns sentences from the language's shared pool with translation, literal gloss, and audio URLs. Pass grammar_point_id to get only sentences that exercise a specific grammar pattern (the server-side filter is by grammar point, not free-text). Use this to pull real example sentences for a structure the learner is working on.
Parameters
grammar_point_idOptional · string | null-
Optional grammar-point id: return only sentences that exercise this grammar point. Omit for the language's full active sentence pool.
Default:
null languageOptional · string | null-
Optional language code (e.g. 'sw', 'ga'). Defaults to the learner's active language when omitted. A locked or frozen language raises a remediation error.
Default:
null limitOptional · integer-
Max sentences (1-200, default 50).
Default:
50Minimum: 1 · Maximum: 200
offsetOptional · integer-
Sentences to skip for pagination.
Default:
0Minimum: 0
Result schema
{
"additionalProperties": true,
"type": "object"
}Access your data another way
Link to “Access your data another way”For scripts and dashboards, use the personal API. For a copy of your learning data, follow the data export request instructions.
If setup fails, contact support with the client you are using and the error you see. Do not include passwords, access tokens, or sign-in codes.