STUSYM MCP Server - Documentation

STUSYM provides an MCP (Model Context Protocol) server that gives AI assistants access to school timetable data: teachers, classes, subjects, rooms, and timetable events. This page describes the available tools and how to connect.

MCP URL: https://mcp.stusym.com
Protocol: MCP 2025-03-26, JSON-RPC 2.0, Streamable HTTP
Authentication: OAuth 2.0 Authorization Code Flow + PKCE, bearer-token only

Authorization model: Open client registration, validated redirect_uri, instance-admin authorization boundary, and per-tool OAuth scopes.

Available Tools

Tool	Description	Type
System
`get_instance_info`	School metadata, active days, and time slots	read
Teachers and Users
`list_users`	List teachers and users with filters	read
`get_user`	User detail	read
`create_user`	Create a user or teacher	write
`update_user`	Update a user	write
`delete_user`	Delete a user	destructive
Classes
`list_classes`	List classes with filters	read
`get_class`	Class detail	read
`create_class`	Create a class	write
`update_class`	Update a class	write
`delete_class`	Delete a class	destructive
Subjects
`list_subjects`	List subjects with filters	read
`get_subject`	Subject detail	read
`create_subject`	Create a subject	write
`update_subject`	Update a subject	write
`delete_subject`	Delete a subject	destructive
Rooms
`list_rooms`	List rooms with filters	read
`get_room`	Room detail	read
`create_room`	Create a room	write
`update_room`	Update a room	write
`delete_room`	Delete a room	destructive
Timetable
`list_timetables`	Timetable events with filters by teacher, class, room, or day	read
`get_timetable`	Timetable event detail	read
`create_timetable`	Create an event with automatic conflict detection	write
`update_timetable`	Update an event with automatic conflict detection	write
`delete_timetable`	Delete a timetable event	destructive

Usage Examples

Example 1 - Reading the timetable
Prompt: "Who teaches Maths in class 2.A and when is their next lesson?"
Result: AI calls list_timetables filtered by class and subject and returns the teacher name, day, and period.

Example 2 - Conflict detection
Prompt: "Schedule Maths for class 1.A on Monday at 8:00 in room 101 with teacher Novak."
Result: AI calls create_timetable. The server automatically checks teacher, class, and room conflicts and returns a warning if a conflict exists.

Example 3 - Data administration
Prompt: "Create a new teacher named Peter Kral with code KRL and email [email protected]."
Result: AI calls create_user with the teacher role and returns a confirmation with the assigned ID.

Integration questions: [email protected]