Institflow מריצה שרת Model Context Protocol בכתובת /mcp (Streamable HTTP, חסר מצב — כל קריאה עצמאית, ולכן הוא מתרחב כמו כל בקשת API אחרת). הוא חושף את אותם שירותי דומיין שכל נקודת קצה של REST קוראת להם, דרך 74 כלים מוכווני משימה, קומץ משאבים לקריאה בלבד וכמה prompts בסגנון דוחות — כך שסוכן AI (Claude, או כל לקוח MCP) יכול לחפש תלמידים, לבדוק לוח זמנים, לרשום נוכחות או לנסח דוח התקדמות, תוך שימוש בהרשאות של הקורא עצמו בדיוק, לעולם לא יותר.
Institflow היא שרת ההרשאות של OAuth 2.1 עבור זה — אין צורך במפתח API נפרד או בטוקן ידני. לקוח MCP תקני מגלה לבד את כל מה שהוא צריך:
הוא מביא GET /.well-known/oauth-protected-resource (RFC 9728) מתוך אתגר ה-WWW-Authenticate של /mcp, ואז GET /.well-known/oauth-authorization-server (RFC 8414) לנקודות הקצה של הטוקן, הרישום וההרשאה.
אם עדיין אין לו client_id, הוא רושם אחד דינמית: POST /oauth/register (RFC 7591 — לקוח ציבורי, בלי סוד; אפשר לכבות את נקודת הקצה הזו לכל הדייר בהגדרה OAUTH_DYNAMIC_REGISTRATION אם אתם מעדיפים לרשום לקוחות מראש בעצמכם).
הוא פותח GET /oauth/authorize עם PKCE (S256 — חובה, לא רשות, תחת OAuth 2.1) בדפדפן שלכם. אתם מתחברים (אם צריך) ומגיעים למסך הסכמה שמראה בדיוק לאיזה דייר/חברות אתם מתחברים ומה הלקוח יכול לעשות.
אחרי שאישרתם, הלקוח מחליף את קוד ההרשאה — POST /oauth/token עם ה-code_verifier של PKCE — בטוקן גישה (JWT רגיל של Institflow, רק עם typ: "mcp") ובטוקן רענון שתקף ל-30 יום.
עצם קבלת טוקן דורשת את ההרשאה mcp.access על החברות שאיתה אתם מתחברים — חבר צוות שאין לו אותה (רוב תפקידי secretary/teacher כברירת מחדל) נדחה בשלב ההסכמה, לפני שהונפק טוקן כלשהו. בנוסף, כל כלי בודק את ההרשאה המוצהרת שלו בכל קריאה — זהה למה שנקודת הקצה המקבילה ב-REST הייתה דורשת.
כלים המסומנים למטה כהרסניים דורשים גם mcp.destructive. קריאה לכלי כזה בלי confirm: true לעולם אינה משנה דבר — היא מחזירה תצוגה מקדימה של מה היה קורה (למשל “היה משנה את הסטטוס מ-active ל-withdrawn”) ואת requiresConfirmation: true. הסוכן (או האדם שמפעיל אותו) קורא שוב לאותו כלי עם confirm: true כדי לבצע בפועל. כל קריאה — תצוגה מקדימה או ביצוע — נרשמת ביומן הביקורת עם channel: "mcp", שם הכלי, וגיבוב של הארגומנטים שלו (לעולם לא הארגומנטים הגולמיים, שעשויים להכיל מידע אישי).
כל הכלים, נוצרים ישירות מ-apps/api/src/modules/mcp/tools/*.ts — בדיוק המקור ששרת ה-MCP עצמו רושם באתחול.
Academics
כלי
תיאור
הרשאה
פעולה הרסנית
cancel_session
Cancel a scheduled class session, with a reason. Destructive: previews unless confirm: true is passed.
groups.write
כן
create_group
Create a new teaching group (class section) for a course, with an optional weekly schedule.
groups.write
לא
drop_enrollment
Drop a student's enrollment from a group. Destructive: previews unless confirm: true is passed.
enrollments.write
כן
enroll_student
Enroll a student into a teaching group.
enrollments.write
לא
get_group
Get full details for one teaching group by id.
groups.read
לא
get_schedule
Get scheduled class sessions for a group, teacher, or student within an optional date range. Exactly one of groupId/teacherStaffId/studentId is required.
groups.read
לא
list_courses
List the course catalogue (subjects/programs offered), optionally filtered by category or active status.
courses.read
לא
list_groups
List teaching groups (class sections), optionally filtered by branch, course, status, or teacher.
groups.read
לא
transfer_student
Transfer a student's enrollment from their current group to another group (drop + enroll in one operation). Destructive: previews unless confirm: true is passed.
enrollments.write
כן
Admin
כלי
תיאור
הרשאה
פעולה הרסנית
audit_search
Search the tenant's audit log by action, entity, actor, or date range.
audit.read
לא
dashboard_summary
Owner/manager dashboard summary — currently the tenant-wide billing summary (outstanding balance, collections, overdue).
invoices.read
לא
get_settings
Get the tenant's effective settings (general, attendance, grading, billing, notifications, curriculum, reminders).
settings.manage
לא
invite_member
Invite a new member to the tenant by email, with a role. Destructive: previews unless confirm: true is passed.
members.manage
כן
list_members
List members of the current tenant, with their assigned roles.
members.manage
לא
list_roles
List every role (system and custom) in the tenant, with its permissions.
roles.manage
לא
set_member_roles
Set a member's complete role assignment (within one branch scope, or tenant-wide) to exactly the given list of role ids. Destructive: previews the add/remove diff unless confirm: true is passed.
members.manage
כן
update_settings
Update one or more tenant settings keys. Destructive: previews the before/after values unless confirm: true is passed.
settings.manage
כן
Assessment
כלי
תיאור
הרשאה
פעולה הרסנית
create_exam
Create a new exam/quiz/homework/project for a group.
assessment.write
לא
generate_progress_report
Queue generation of a progress report for a student or an entire group over a period. Asynchronous — returns immediately once queued.
assessment.write
לא
get_student_grades
Get a student's grades (per-group weighted average and per-exam breakdown), optionally scoped to one group.
assessment.read
לא
publish_exam
Publish an exam so its results become visible to students/guardians. Destructive: previews unless confirm: true is passed.
assessment.write
כן
record_results
Bulk-record (or update) student scores for an exam.
assessment.write
לא
send_progress_reports
Send every published (not-yet-sent) progress report for a student or group to guardians. Destructive: previews the list unless confirm: true is passed.
assessment.write
כן
assignments
כלי
תיאור
הרשאה
פעולה הרסנית
curriculum.assignments.create
Create an assignment unit in a course: a lesson of kind "assignment" plus its instructions, due date, max score, late policy and allowed submission kinds, in one transaction.
curriculum.write
לא
curriculum.assignments.grade_submission
Grade a submission (score at most the assignment’s max score, optional feedback). Emits assignment.graded.
curriculum.assignments.grade
לא
curriculum.assignments.list_submissions
List an assignment’s submissions (cursor-paginated), optionally filtered by status. lessonId is the assignment unit’s id, or the id of the video lesson that carries the task.
curriculum.assignments.grade
לא
curriculum.assignments.publish_to_gradebook
Publish every currently-graded submission into the gradebook as a "homework" exam per group — upserts on repeat. Destructive: the first publish for a group creates and publishes a real exam, notifying students/guardians, so it previews unless confirm: true is passed.
curriculum.assignments.grade
כן
curriculum.assignments.return_submission
Send a submission back to the student for revision (clears any earlier grade).
curriculum.assignments.grade
לא
curriculum.assignments.update
Update an assignment’s own fields (instructions, due date, max score, late policy, allowed submission kinds). Lesson-shared fields (title, section, drip gate) go through update_lesson.
curriculum.write
לא
curriculum.lesson_tasks.remove
Remove the task under a video lesson. Destructive: previews (with the number of submissions that would be deleted with it) unless confirm: true is passed, which also confirms deleting those submissions.
curriculum.write
כן
curriculum.lesson_tasks.set
Create or replace «مهمة هذا الدرس», the task under a video lesson (instructions, due date, max score, late policy, accepted submission kinds). Submissions, grading and the gradebook publish then use the curriculum.assignments.* tools with the same lessonId.
curriculum.write
לא
Attendance
כלי
תיאור
הרשאה
פעולה הרסנית
attendance_report
Attendance report for a group (per-student rates) or a single student (full history), within an optional date range.
attendance.read
לא
get_session_roster
Get the attendance roster for a scheduled session — every enrolled student and their current attendance mark, if any.
attendance.read
לא
record_attendance
Bulk-record (or update) attendance marks for every student on a session's roster.
attendance.mark
לא
Billing
כלי
תיאור
הרשאה
פעולה הרסנית
billing_summary
Tenant-wide billing summary — outstanding balance, this month's collections, and overdue counts/totals.
invoices.read
לא
create_invoice
Create a new draft invoice for a student, with one or more line items.
invoices.write
לא
get_invoice
Get full details for one invoice, including its lines and payments.
invoices.read
לא
list_invoices
List invoices, filterable by status (including an "overdue" shorthand), student, guardian, or due-date range.
invoices.read
לא
record_payment
Record a payment against an invoice.
payments.record
לא
student_statement
Get a student's full billing statement — every invoice/payment entry and the running balance.
invoices.read
לא
void_invoice
Void an invoice, with a reason. Destructive: previews unless confirm: true is passed.
invoices.write
כן
curriculum
כלי
תיאור
הרשאה
פעולה הרסנית
create_lesson
Create a lesson in a course. Omit sectionId to use (or auto-create) the course’s default section. audienceGroupIds restricts it to those groups of the course; omit or null for every group.
curriculum.write
לא
delete_lesson
Delete a lesson and its video and progress rows. Destructive: previews (with how many students have progress on it) unless confirm: true is passed.
curriculum.write
כן
get_lesson
Get one lesson by id, including its markdown body and video source.
curriculum.read
לא
grant_course_access
Grant a student access to a self-paced (video) course. Idempotent — granting twice returns the existing enrollment.
enrollments.write
לא
list_course_curriculum
List a course’s curriculum: its sections, each with the lessons inside it. Published lessons only unless includeDrafts is true.
curriculum.read
לא
publish_lesson
Publish a lesson so enrolled students can see it. Destructive: notifies real people, so it previews unless confirm: true is passed.
curriculum.publish
כן
revoke_course_access
Revoke a student’s self-paced course access. Destructive: previews unless confirm: true is passed.
enrollments.write
כן
set_lesson_video
Attach a video to a lesson from a YouTube URL. The URL is validated and normalized exactly as the web editor does.
curriculum.write
לא
student_course_progress
One student’s progress through their video courses — lessons completed vs. available, and the last lesson they opened.
curriculum.read
לא
update_lesson
Update a lesson’s title, summary, markdown body, estimate, release rules or audience (audienceGroupIds: a list of the course’s group ids to restrict the lesson to those groups, null for every group).
curriculum.write
לא
Notifications
כלי
תיאור
הרשאה
פעולה הרסנית
get_notification_rule
One notification type: the effective rule, the override the institute made, what the type allows and locks, and per channel whether it can deliver, who bills it and the price per message.
notifications.read
לא
get_notification_spend
Notification usage this month per channel and, when the install is on the Institflow messaging relay, the credit balance.
notifications.manage
לא
list_notification_rules
The notification rules of the institute: for every kind of notice the system sends — absence, invoices, payments, grades, lessons, assignments, quizzes, class and deadline reminders, subscription alerts — who receives it, on which channels, and whether the institute changed it from the Institflow default.
notifications.read
לא
notification_usage
Notification channel usage/cost for a billing period (defaults to the current month, format YYYY-MM).
notifications.read
לא
preview_notification_rule
Changes nothing: the estimated monthly cost (a range, in credit units — 10 000 units per credit), how many people a proposed rule would reach, whether saving it needs cost confirmation, and warnings. Omit `rule` to describe the current rule.
notifications.read
לא
reset_notification_rule
Deletes the override the institute made for one notification type: it goes back to the Institflow default. Destructive: previews the change unless confirm: true is passed. Going back to the default can switch the type or a paid channel on again; that additionally needs confirmCost: true, exactly like update_notification_rule.
notifications.manage
כן
send_message
Send a message to a student/guardian/group/branch audience via the notification channel ladder (email/SMS/WhatsApp/push, falling back down the ladder). SMS/WhatsApp are platform/licence-approved per tenant — naming one explicitly in `channels` when it is not approved is rejected; leaving `channels` unset falls through the ladder to an approved channel (in-app always reachable) instead. Destructive: previews recipient count and quota impact unless confirm: true is passed.
notifications.send
כן
update_notification_rule
Replaces the override the institute made for one notification type (a field left out goes back to the Institflow default). Destructive: previews before/after AND the estimated cost unless confirm: true is passed. A change that raises what the institute pays for — a paid channel switched on, recipients, lead times or scope added — additionally needs confirmCost: true, so an assistant cannot spend credit by accident even with confirm.
notifications.manage
כן
quizzes
כלי
תיאור
הרשאה
פעולה הרסנית
curriculum.quizzes.add_question
Add a question to a quiz. Returns the whole quiz (questions included).
curriculum.quizzes.manage
לא
curriculum.quizzes.create
Create a quiz unit in a course: a lesson of kind "quiz" plus its settings, in one transaction. No questions yet.
curriculum.quizzes.manage
לא
curriculum.quizzes.delete_question
Delete a quiz question. Returns the whole quiz (questions included).
curriculum.quizzes.manage
לא
curriculum.quizzes.grade_answer
Grade a short-answer (short_text) answer (points at most the question’s own points). Finalises the attempt’s score/passed once nothing is left ungraded. Emits quiz.graded on finalisation.
curriculum.assignments.grade
לא
curriculum.quizzes.list_attempts
List a quiz’s attempts (cursor-paginated), optionally filtered by student or status.
curriculum.assignments.grade
לא
curriculum.quizzes.publish_to_gradebook
Publish each student’s best fully-graded attempt into the gradebook as a "quiz" exam per group — upserts on repeat. Destructive: the first publish for a group creates and publishes a real exam, notifying students/guardians, so it previews unless confirm: true is passed.
curriculum.assignments.grade
כן
curriculum.quizzes.reorder_questions
Whole-list reorder of a quiz’s questions. Returns the whole quiz (questions included).
curriculum.quizzes.manage
לא
curriculum.quizzes.update
Update a quiz’s own settings (time limit, attempts allowed, shuffle, show-answers-after, pass score, due date). Lesson-shared fields go through update_lesson.
curriculum.quizzes.manage
לא
curriculum.quizzes.update_question
Update a quiz question. Returns the whole quiz (questions included).
curriculum.quizzes.manage
לא
Students
כלי
תיאור
הרשאה
פעולה הרסנית
add_guardian
Attach a guardian to a student — either link an existing guardian by id, or create a new one and link it.
guardians.write
לא
create_student
Create a new student record in the current tenant.
students.write
לא
get_student
Get full details for one student by id, including guardians and status.
students.read
לא
search_students
Search/list students in the current tenant, filtered by free-text query, status, branch, group, or tag. Cursor-paginated.
students.read
לא
set_student_status
Change a student's lifecycle status (lead/active/inactive/graduated/withdrawn). Destructive: previews the transition unless confirm: true is passed.
students.write
כן
update_student
Update a student's profile fields (name, contact info, tags, ...). Does not change status — use set_student_status for that.