Connector reference

What your assistant can do with Chavruti

Chavruti is a Model Context Protocol server at https://api.chavruti.ai/mcp (streamable HTTP). It has30 tools: 17 that read and 13 that record your learning. None of them sends anything outside Chavruti, and none charges or buys anything.

Connecting

Endpoint: https://api.chavruti.ai/mcp. Step-by-step for each assistant: how to connect.
Authentication: OAuth 2.1 with PKCE (S256) and dynamic client registration, for public clients and for confidential ones (client_secret_basic or client_secret_post). The 401 response points to/.well-known/oauth-protected-resource/mcp; the issuer is https://app.chavruti.ai, and the learner approves each connection as full access or view only. Access tokens last 14 days; refresh tokens rotate on every use. An assistant that can't do OAuth can use a key made in the app (Settings → Assistants), sent as Authorization: Bearer cv_…. Every connection reaches one learner's record, is stored only as a hash, and can be revoked in Settings with immediate effect.
Server instructions: on connecting, the server tells the assistant how to learn with the person: quote only text that get_text returned, ask before telling, follow the learner's settings, never assume belief, observance or background, and record as it goes.
Results: every tool returns {"ok": true, …} or{"ok": false, "error", "hint"}, and the hint says how to recover. A view-only connection getsview_only from every tool that records.
Cards: 14 read tools also draw a card under their result in assistants that show MCP Apps (the reader, the path, the maps). The card shows the same result; it fetches nothing from anywhere else.

Classes

Read tools change nothing: texts with each word's pronunciation in your tradition, your settings, your path, what's due for review.
Write tools change only your own learning record and settings: what you learned and reviewed, your place in a book, the tracks you're on, a short note for next time.

Tool	Class	What it does
`find_lemmas` Find dictionary entries query	Read	Dictionary entries (lemmas) by spelling, with or without nikud ("צורי", "צוֹרִי"), or by an English word in the gloss ("balsam"): id, headword, gloss, part of speech, language, source (oshb, wiktionary, jastrow) and the start of the definition. Use it to find the right entry before suggest_correction(kind="meaning", proposed=<id>), when a word in get_text seems linked to the wrong one. Read the definitions; don't guess from the gloss alone.
`find_text` Find a text query	Read	Find a passage from a ref ("Exodus 20", "Rashi on Genesis 1:1"), a book or tractate name ("Pirkei Avot", "Berakhot"), a prayer's name in English or Hebrew ("Shema", "Ashrei", "Amidah", "Aleinu", "Birkat HaMazon", "Lekha Dodi", "אשרי"), an English phrase ("love your neighbor"), or Hebrew words with or without nikud ("שמע ישראל"). A prayer comes back once per service it's in (kind "prayer"), the learner's nusach first (settings.nusach: Ashkenaz, Sefard or Edot HaMizrach), each with its ref, title and nusach; pick the one that fits (ask if unsure). Name a nusach to get only that one ("Sefard Amidah", "Amidah Edot HaMizrach"). Searches the Torah, the Mishnah, the Talmud and Rashi on the Torah (a match whose ref starts "Rashi on" is a Rashi comment). Talmud refs go by amud ("Berakhot 2a", "Bava Metzia 21b:3", Hebrew "ברכות ב"); a bare tractate name ("Bava Metzia") returns both the Gemara and the Mishnah. Returns refs for get_text.
`get_calendar` Hebrew calendar · card date?, hebrew_date?, find?	Read	Hebrew calendar data: "what's this week's parsha", "when is Pesach", "what's the Hebrew date", "is today Rosh Chodesh". With no arguments: today in the learner's time zone. date: a civil date, YYYY-MM-DD. hebrew_date: a Hebrew date in English letters, "15 Nisan 5787" or "15 Nisan" (the next one from today, or from date). find: a holiday, fast or parsha by name ("Pesach", "Chanukah", "Tisha B'Av", "Rosh Hashanah", "Erev Yom Kippur", "Shabbat HaGadol", "Noach", "Vayera"): the next one on or after today (or date). Returns the day (Hebrew date, holidays, fast, Rosh Chodesh, Chol HaMoed, eves), its week's Shabbat with the parsha (name in the learner's spelling and in Hebrew, its verse range and the seven aliyot and maftir as refs, a special Shabbat; on a festival Shabbat, the festival and next_parsha), coming_up (the next few holidays), and calendar: the schedule used, Israel or the diaspora (the learner's setting, or inferred: then say so, and ask which they follow before leaning on a date where the two differ, such as a second festival day or a parsha in a split week). Days run by date, not sunset: a holiday "begins the evening before". It is calendar data and assumes nothing about observance: a secular or academic learner may want the parsha for study or culture. The ranges are refs only: read the verses with get_text, never from memory.
`get_guide` Guide topic	Read	How to run a kind of session: welcome, learn, review, kriah, ivrit, chumash, mishnah, gemara, mussar, settings; or 'method' for the rules, boundaries, lenses, practice frames and ways of learning. Read before a longer session.
`get_learner` The learner · card	Read	The learner's record and settings: counts of what they know by kind and state, tracks with stages, positions in each text, and every setting (tradition, fading, the Name, lenses, practice frame).
`get_library` Library · card	Read	What texts are loaded, by corpus (tanakh, mishnah, rashi, siddur, bavli): each book or tractate with its number of units (unit_kind) and first_ref to open it: chapters; for rashi the verses it comments on; for the siddur, in three nusachim (Ashkenaz, Sefard, Edot HaMizrach; the category names it), each service or group (Weekday Shacharit, Kabbalat Shabbat, Blessings...) with its number of prayers; for bavli (the Talmud, 37 tractates) the amudim.
`get_mussar` Mussar · card	Read	This week's middah (of the thirteen), where they are in the cycle, and recent check-ins. Private.
`get_my_corrections` My suggested corrections · card	Read	The corrections this learner suggested (here or in the app), newest first, each with its status: pending (waiting for review), approved (fixed in the data for everyone), rejected (kept as is; review_note says why) or superseded (another correction to the same thing was approved). new=true marks a decision they haven't seen: tell them about it, briefly and warmly, at a natural moment. Use when they ask what happened to a report.
`get_path` Path · card track?	Read	The tracks (kriah, ivrit, chumash, mishnah, gemara, mussar) with their stages and milestones, and where the learner is on each. Use it to choose a track or to see what the next milestone is.
`get_progress` Progress maps · card corpus?	Read	Completion maps: for each book or tractate, passages learned, reviewed and memorized out of the total; and reviews by day for the last six months. corpus: tanakh, mishnah, rashi, siddur or bavli. A bavli tractate (Shas) also has amudim / amudim_learned, dapim / dapim_learned (a daf counts when both amudim are learned) and started: the amudim with something learned, each with learned and total segments.
`get_review` Due for review · card limit?, kind?	Read	Items due for review now (words, roots, mishnayot...), up to the learner's round size or limit. Ask each without revealing the answer; then record_review once for the round. kind filters (lemma, form, segment, term...).
`get_settings` Settings · card	Read	The learner's settings with what each one means and its options. They persist and apply everywhere. nusach_in_effect: the siddur find_text puts first (their nusach, or the one that goes with their tradition).
`get_setup` Getting started · card	Read	Their steps from signing up to learning, each with done true or false: connect an assistant (web app), meet your chavruta, learn a first passage, and a first review (all with you, in conversation), then add a card before the 14-day free trial ends (web app; no card is needed to start). Web-app steps you can't do: send the link. get_today already carries the next one as setup; call this when they ask what's left. Lead the next conversational step yourself, one at a time; never as a checklist. Don't press the card: it becomes the next step only near the trial's end.
`get_text` Read a text · card ref, words?, commentary?	Read	The only source of text you may quote, the commentaries included. ref: a passage like "Genesis 1:1-5", "Genesis 1", "Mishnah Berakhot 1:1", "Berakhot 1" (a plain number is the Mishnah), the Talmud by amud: "Berakhot 2a", "Berakhot 2a:3", "Berakhot 2a:3-5", "Berakhot 2a-3b", "Bava Metzia 21a" (Hebrew works too: "ברכות ב" is daf 2, both amudim; "ברכות ב." / "ב:" one amud), a graded reader's ref, a siddur ref from find_text ("Siddur Weekday Shacharit 46", the Shema in nusach Ashkenaz; "Siddur Weekday Shacharit 48-69", the whole weekday Amidah; "Siddur Sefard ..." and "Siddur Edot HaMizrach ..." are those nusachim; siddur segments also carry prayer / prayer_he, its place in the service; never recite a prayer from memory), or Rashi on the Torah: "Rashi on Genesis 1:1" (every comment on that verse), "Rashi on Genesis 1" (the chapter), "Rashi on Genesis 1:1-5", or one comment "Rashi on Genesis 1:1:2". Returns each segment's Hebrew (the learner's chosen edition), translation (with their choices for the Name), and, with words=true, every word with: translit in the learner's pronunciation tradition, lemma and gloss (Tanakh words from OSHB/BDB; Mishnah and Talmud words also from Wiktionary or Jastrow's dictionary, lemma ids "jastrow:..."; alternates: n when the lemma was one reading among n+1 the letters allow, which get_word lists), state (what they know: seen / learning / known / null), and show_nekudot / show_translit / show_translation (the fading reader: false means they know it, so don't help with it unless asked). A Rashi segment also has on (the verse it comments on) and dibur_hamatchil (the words of the verse it quotes; those words carry dh=true). commentary="rashi" on a Torah ref adds each verse's Rashi comments (Hebrew and English, no words) under segment["rashi"]; for Rashi word by word, get_text the "Rashi on ..." ref. Rashi doesn't comment on every verse: an empty list means none. Never quote or paraphrase Rashi as his words unless it came from here. The Talmud text (Wikisource edition, CC BY-SA) has no nikud: its words have no translit; any vocalization you offer is yours, say so. Its sources carry a share-alike attribution: show it with the text. At most 40 segments per call; use next / prev / next_part to move on. Includes sources with licenses: show the attribution with the text.
`get_today` Today · card	Read	Start every conversation here. Where they are in each track (continue), how many items are due for review, words known, the last session's note, the one thing worth doing now, and try_next: things they haven't tried, to offer one at a time at a natural pause (record a no with not_now). "new": true means welcome them (get_guide('welcome')). plan: their trial or subscription. When plan.open is false Chavruti is read-only (texts and record still readable; recording tools answer error "read_only"): say plan.note once, kindly, and keep learning without recording. Billing itself is only in the web app; never offer to change it here. corrections_decided > 0: corrections they suggested were decided; get_my_corrections says how. week: the Hebrew date in their time zone, today_is (holidays, fasts, Rosh Chodesh, eves), and the coming Shabbat with its parsha (name in their spelling and Hebrew, range ref, aliyot; a special Shabbat; on a festival Shabbat the festival and next_parsha), and week.calendar: Israel or diaspora, and whether that's inferred. Calendar data, not a cue: mention it only when it fits (they ask, it's a holiday, or they're on the chumash track), and never assume observance. week.chumash (on the chumash track): how much of this week's parsha they've learned and where their own position is; offer its first aliyah at most as an option, and keep to the place they chose.
`get_word` A word · card word, form?	Read	A word (Hebrew with or without nikud, or a lemma id like "oshb:H1254a", "wikt:..." or "jastrow:..."): its lemma, meaning, root and root family, its forms in the texts, how it's pronounced in every tradition, where it occurs, and what the learner knows of it. lemma.source says whose definition it is: "oshb" (Brown-Driver-Briggs, for Tanakh words), "wiktionary", or "jastrow" (Jastrow's 1903 dictionary of Talmudic and Midrashic Hebrew and Aramaic, for Mishnah words; its first sense is sometimes the etymological one, so read the definition before explaining, and credit it with lemma.attribution when you quote it). Mishnah and Talmud words are linked to Jastrow automatically (Mishnah: spelling, prefixes, the Tanakh's analysis; Talmud, which has no vowels: Jastrow citing the passage, the letters with prefixes and suffixes taken off, or the most-cited entry), so roughly one link in ten may be the wrong entry: if the definition doesn't fit the passage, say so rather than forcing it. linked_by.method says how ("dominant": several entries fit and this one is by far the most used). alternates lists the other entries the letters fit (lemma, headword, gloss, why), most likely first: when the chosen meaning doesn't fit the passage, or the learner asks, mention them as other possible meanings, labeled as such, not as the meaning (and if the learner agrees the link is wrong, suggest_correction). A word with no lemma may still list alternates: readings offered without a link, never the meaning. form: the word as written in the passage (its text from get_text) when word is a lemma id, so pronunciations (and alternates) are of that exact form (pronounced_form says which); a spelling in word does this by itself. cognates (when there are any): the same word in the sister language, Aramaic for a Hebrew lemma and Hebrew for an Aramaic one (lemma, headword, gloss, language, root, and for a Hebrew cognate its root_family). relation says how they correspond, by the regular sound changes between the two languages: "cognate (Aramaic ד = Hebrew ז)" (דהב/זהב "gold", דכר/זכר), ת = ש (תלת/שלש "three", תור/שור "ox"), ט = צ (טלל/צל "shade", נטר/נצר), ע = צ (ארעא/ארץ, עמר/צמר "wool"), ס = ש (sin); ־א is the Aramaic definite ending, ־ין/־יא its plural (Hebrew ־ים); "cognate (same letters)" when nothing changed. kind "equivalent" is a different word with the same meaning (בר "son" for בן, אזל "go" for הלך), labeled "Hebrew equivalent", never a cognate. why gives the evidence (Jastrow names the Hebrew word; the meanings agree). Use it to connect a Talmud word to Hebrew the learner knows ("the Aramaic דהב is the Hebrew זהב: ד for ז"). It is comparative linguistics, made by rule and checked by meaning: present it as a connection between the languages, labeled as such, not as the word's meaning in the passage (that is lemma), and don't build an etymology beyond what relation and why say.
`list_traditions` Pronunciation traditions · card word?	Read	The pronunciation traditions a learner can choose (Israeli, Sephardi, Ashkenazi and its variants, Yemenite, academic...), each with a description, and how a sample word sounds in each. word: a vocalized word to show (default בְּרֵאשִׁית). Use when choosing or explaining a tradition.
`enroll` Enroll in a track track, stage?, pace?, goal?, status?	Write	Start (or pause, or finish) a track: kriah, ivrit, chumash, mishnah, gemara, mussar. stage: where to start if they're past the beginning (get_path shows the stages). pace and goal in their own words.
`make_reader` Make a graded reader title, lines, topic?, force?	Write	Store a short story you wrote at the learner's level: lines = [{"he": "fully vocalized Hebrew", "en": "English"}], 6-15 short lines, mostly words they know (get_learner / get_review) and a few new. The server measures how much they know; under 90% it isn't stored and returns the unknown words to rewrite (force=true to keep a stretch). Stored readers open in get_text like any text. Your nekudot are marked unverified.
`mark_known` Mark known / set aside items, state?	Write	The learner's own call about words or items: known (they know it; skip review; recorded as their claim), set_aside (stop reviewing it), or learning (put it back in review).
`mark_milestone` Milestone track, key, done?	Write	Tick (or untick) a milestone from get_path when the learner has really reached it. Celebrate it.
`not_now` Not now key	Write	The learner said no to a try_next suggestion: record its key so it isn't offered again.
`record_checkin` Mussar check-in note?, score?, middah?	Write	A mussar check-in on this week's middah (or a named one): a note in their words, a 1-5 score only if they want.
`record_learning` Record learning ref, worked_on?, completed?, track?, mode?, note?	Write	After learning a passage: every word in it becomes "seen"; the words in worked_on (as written in the text, or lemma ids, or "letter:א" / "term:..." items) start review; completed marks the passage learned (and for Mishnah adds it to review) and moves their position to what follows. note: a line for next time. Call as you go.
`record_review` Record review results	Write	After a review round: results = [{"kind": ..., "key": ..., "rating": "again"\|"hard"\|"good"\|"easy"}] using kind and key from get_review. Rate from how it went (again = didn't know it). Schedules each item's next review.
`save_session` Save session note note, track?, refs?	Write	A short note for next time: where you stopped, what was hard, what they want to pick up.
`set_name` Set name name	Write	What the learner likes to be called. Ask early; never greet them by their email address.
`set_position` Move to a passage ref, track?	Write	Set where the learner is in a text (where get_today's continue will point), e.g. when they jump ahead.
`suggest_correction` Suggest a correction kind, ref?, position?, word?, lemma?, tradition?, proposed?, note?, quoted?	Write	Send Chavruti's staff a correction to something Chavruti shows. Use it when the learner says something is wrong, or when you notice a mismatch yourself (a gloss that doesn't fit the passage, a word linked to the wrong dictionary entry, a reading that's off, a typo in the text) and the learner agrees it looks wrong. Ask them first; never file one on your own. kind: "meaning" (the word is linked to the wrong dictionary entry), "gloss" (the right entry, but its short English gloss misleads), "pronunciation" (the transliteration is wrong in a tradition), "text" (a typo, a missing or extra word in the Hebrew/Aramaic), "translation" (a problem in the English). Where: ref is the one segment as get_text gave it ("Genesis 1:1", "Berakhot 2a:3"); for a word also position (the word's i from get_text). Without a passage, word (as written) works for meaning, gloss and pronunciation, and lemma (a lemma id) for gloss. text and translation need ref. proposed: for meaning, the lemma id of the right entry (from get_word or find_lemmas), or "none" when no entry fits (then say in note what the word means here); for gloss, a short English gloss; for pronunciation, the transliteration as it should read (tradition: which one; default the learner's); for text or translation, the corrected wording (or leave it out and describe the problem in note). quoted: what Chavruti shows now, quoted exactly from get_text or get_word (the server also records what it shows). note: the problem in a sentence or two, in plain words. Afterwards, never say it's fixed or changed: tell the learner it went to review, a person will look at it, and they'll see the outcome under Your suggestions in the app (and get_my_corrections). An identical suggestion someone already sent is joined, not duplicated.
`update_settings` Update settings changes	Write	Change settings the learner asked to change, e.g. {"tradition": "ashkenazi"}, {"divine_name": "hashem"}, {"nekudot": "always"}, {"lenses": ["traditional", "academic"]}, {"practice": "secular_humanist"}, {"nusach": "edot_hamizrach"} (which siddur's wording; null goes back to following the tradition), {"calendar": "israel"} or "diaspora" (which schedule the parsha and holidays follow; null infers it again), {"timezone": "Europe/London"} (an IANA zone; the web app usually sets it). See get_settings for every option. Only on the learner's request; never to suit your own preference.