hdls Learn

hdls Learn is a headless, MCP-native learning management backend. It manages courses, lessons, and enrolments, operated entirely through named tools your AI assistant calls. It stands in for tools like TalentLMS, Docebo — same job, no UI to run.

💬 Just ask

"Create a course for Acme, then show me my courses."

You don't call these tools yourself — just tell your assistant in plain English. Everything below is the reference for when you (or your assistant) want the exact details.

How Learn is organized

The headline entity is the course — start there, then attach the rest to it. Records connect by reference: a lesson links to a course; an enrolment links to a course; a lesson_progress links to an enrolment and a lesson; a certificate links to an enrolment. The learning_event table is an append-only timeline — every change and note lands there and is never edited or deleted.

Entity	Purpose	Relates to
`course`	A course made of ordered lessons; learners enrol and progress through it.	—
`lesson`	Ordered content unit within a course (text, video, quiz, etc.).	`course`
`enrolment`	A learner registration in a course tracking progress, score, and completion.	`course`
`lesson_progress`	Per-lesson completion/score for an enrolment; aggregates into enrolment.progress.	`enrolment`, `lesson`
`certificate`	Credential issued when a learner passes a course; serial enables public verification.	`enrolment`
`learning_event`	Append-only learning timeline: enrolment, lesson, quiz, and completion activity.	`enrolment`

Common workflows

Each line is one real sequence of tool calls — your assistant chains them for you.

Set up a course end to end: create_course → enroll_learner → track_progress

Tools

Call these at https://hdls.ai/api/mcp/lms. Required fields you must supply; optional fields refine the call. You never pass tenant_id — it is stamped server-side.

Create

Tool	What it does	Required	Optional
`create_course`	Create a new course.	`title`	`description`, `category`, `level`, `status`, `instructor`, `duration_mins`

Update & advance

Tool	What it does	Required	Optional
`enroll_learner`	Enroll a learner.	`id`	—
`track_progress`	Track progress on a course.	`id`	—
`issue_certificate`	Issue a certificate.	`enrolment_id`, `learner`, `serial`	`issued_at`, `expires_at`, `url`, `data`

Find & read

Tool	What it does	Required	Optional
`search_courses`	Search courses by free-text and/or column filters (tenant-scoped, paginated).	—	`search`, `filters`, `limit`, `orderBy`

Field lists come from the product's live schema and are embedded in each tool's own description — read the tool description for the exact, current fields.

Field reference

Every field you can set on each record. Custom fields you add live alongside these in data.

`course`

Field	Type	Required	Notes
`title`	text	Yes	Display name.
`description`	text
`category`	text
`level`	text
`status`	text		Lifecycle state.
`instructor`	text
`duration_mins`	number
`pass_threshold`	numeric(5,2)
`data`	json		Free-form JSON — custom fields live here.

`lesson`

Field	Type	Required	Notes
`course_id`	id	Yes	Links to a `course`.
`title`	text	Yes	Display name.
`content`	text
`content_type`	text
`position`	number
`duration_mins`	number
`data`	json		Free-form JSON — custom fields live here.

`enrolment`

Field	Type	Required	Notes
`course_id`	id	Yes	Links to a `course`.
`learner`	text	Yes
`status`	text		Lifecycle state.
`progress`	numeric(5,2)
`score`	numeric(5,2)
`enrolled_at`	timestamp
`completed_at`	timestamp
`due_at`	timestamp
`data`	json		Free-form JSON — custom fields live here.

`lesson_progress`

Field	Type	Required	Notes
`enrolment_id`	id	Yes	Links to an `enrolment`.
`lesson_id`	id	Yes	Links to a `lesson`.
`status`	text		Lifecycle state.
`score`	numeric(5,2)
`time_spent_secs`	number
`completed_at`	timestamp
`data`	json		Free-form JSON — custom fields live here.

`certificate`

Field	Type	Required	Notes
`enrolment_id`	id	Yes	Links to an `enrolment`.
`learner`	text	Yes
`serial`	text	Yes
`issued_at`	timestamp
`expires_at`	timestamp
`url`	text
`data`	json		Free-form JSON — custom fields live here.

Tailor it with custom fields

Add fields without a schema change. add_custom_field defines one, list_custom_fields shows what's defined, and promote_custom_field (admin) shares a personal field with the whole workspace. The value lives in each row's data (JSON) and is set and read through the normal record tools. See Products, tools & custom fields for the full model.

Roles & safety

Tenant isolation is automatic. Your credential is pinned to one workspace; you never pass tenant_id, and you can only ever see your own data (enforced by Postgres row-level security).
Role-gated. Permissions run reader < member < admin < owner. Installing a product and promoting a custom field workspace-wide need admin/owner.
History is append-only. The learning_event timeline is never edited or deleted — it's your audit trail.

Connect

On the concierge (https://hdls.ai/api/mcp), run install_product({ slug: "lms" }) (admin/owner) to enable it for your workspace, then add https://hdls.ai/api/mcp/lms as a connector in your assistant — see Connect your assistant.

A worked example

The literal call your assistant makes when you ask it to create the headline record:

Tool: create_course
Arguments: {
  "title": "Onboarding 101"
}

See All products · Connect your assistant · Automation