It is possible to use AI Agents such as Claude / Claude Code / Cursor / Chat GPT / Antigravity to generate MiniLessons. This feature is still in develpment, but at Poodll we are using internally. You are welcome to try it out on your own Moodle site.
Once it is set up you should be able to use the intelligence of the agent to:
i) create importable MiniLesson content .. and import it. OR
ii) prepare inputs to MiniLesson's internal AI generate feature .. and trigger the AI generation
The first option (creating importable content) offers more flexibility because Minilesson's internal Ai Generate feature uses pre-built templates that may or may not match the inputs you have or the output you need. But the templates can generate images in the item they create. Your agent can make the decision on which to use, or you can ask it to consult with you.
There are three broad use cases that the API is optimised for:
i) You simply describe what you want, and ask the agent to prepare it for you.
ii) You have a detailed specification, perhaps prepared by Gemini or some other tool, and you just want it turned into Minilessons
iii) You have a paper based lesson (eg a PDF) that should be turned into a set of Minilessons
Requirements
- Poodll MiniLesson version 1.1.43 (Build 2026071800) or greater
- A correctly configured webservice user (see below)
- An ai agent platform such as Claude, Claude Code, Cursor, or Antigravity
The Web Service User and Permissions
First of all web services must be enabled at:
Site administration -> General -> Advanced features
And the REST protocol must be enabled at:
Site administration -> Server -> Web Services -> Manage Protocols
The user (users) must
- Not be site administrators
- Have permission: webservice/rest:use
- Be added to authorized users at :
Site administration -> Server -> Web Services -> External Services - Ai Generation Service - Be enrolled as a teacher in the courses they will make MiniLessons in
The web service user's token
The web service user authenticates with Moodle using a token. Generate the web service user's token at:
Site administration -> Server -> Web Services -> Manage tokens
(Optional ) It is possible for the agent to use a username and password to generate a token (like the Moodle Mobile App does). But this method only works for pure API use (not MCP or GPT) To enable that:
Grant the webservice user the permission: moodle/webservice:createtoken
This allows the agent to generate a token using the web service user's username and password.
Using MCP with Claude Code
Use the following command to add the MCP server (be sure to add your moodle url and token)
claude mcp add --transport http minilesson https://YOUR-MOODLE-SITE/mod/minilesson/mcp.php --header "X-API-Key: YOUR_TOKEN"
Then from within a Claude Code session /mcp should list minilesson and its tools
Using MCP with Claude (desktop app)
Claude for desktop and web both expect OAuth authentication for custom connectors. Since Poodll MiniLesson does not support that, you should add Poodll MiniLesson as an extension to Claude (desktop app). NB it won't work on Claude (web app).
- Download the poodllminilesson.mcpb file. It is linked to at the bottom of this document. Download it.
- Visit Claude (desktop app) settings -> Extensions -> Advanced -> Add Extension
- Select the file you downloaded: poodllminilesson.mcpb
- Enter the MCP file URL for your Moodle server : https://[your moodle url]/mod/minilesson/mcp.php
and your web service token - Enable the extension
Test it by asking it to list the courses you (the web service user) have access to.
Creating a Custom GPT (ChatGPT)
In ChatGPT you can create a custom GPT and use this to call your MiniLesson AI Generate features.
i) In ChatGPT visit: Explore GPTs → Create → Configure
ii) Give the GPT a name, eg "Poodll MiniLessons"
iii) Scroll down and select "actions" or "add an action"
ii) In Scheme, select "Import from URL" and enter: https://[YOUR_MOODLE_URL]/mod/minilesson/openapi.php then press "import"
iii) In Authentication choose "API Key" and "Custom" then enter:
Custom Header Name: X-Api-Key
API Key: [YOUR_TOKEN]
iv) Instructions, paste the following
You make Poodll MiniLessons via the aigen actions. The API spec embeds detailed guidance under x-agent-instructions (authentication, the template vs. direct-compose workflows, and base_lesson_replication). Follow it for the mechanics. Requests come in three kinds - identify which, then follow the matching workflow: 1. SOURCE MATERIAL (an uploaded PDF/doc/image, or a pasted lesson plan) -> reproduce it faithfully as items (direct-compose workflow). OCR images/PDFs yourself first. 2. EXPORTED LESSON AS A TEMPLATE (the user uploads an exported MiniLesson, or asks to base new lessons on an existing one) -> base_lesson_replication: keep each item's type, layout, options and settings; rewrite only the wording per topic; DROP the old base64 images (they belong to the original topic); let audio regenerate from the new text (do not supply audio files). To reuse a lesson already on the site, pull it first with aigen_export_items_json. 3. A DESCRIBED LESSON ("a speaking/listening lesson on comparatives, food theme") -> check aigen_list_templates FIRST and use a template if one fits (templates can generate text, questions and media server-side). Only hand-compose if none fits. Shared steps once you know the content: - POST /aigen_list_itemtypes to see item types (only hasimportdocs=true types can be hand-composed); POST /aigen_fetch_item_type_details {"itemtype":"..."} for each type you will compose, and follow its field spec exactly. - POST /list_courses and confirm the target course (ask if unclear). - POST /aigen_create_empty_lesson {"courseid":...,"title":"..."} to get a cmid. - Then either POST /aigen_import_items_json {"cmid":...,"itemsjson":"<{items:[...]} as a string>"} for composed items, or the template workflow (aigen_create_add_items_ to_lesson + poll aigen_fetch_create_items_status) for generated content. - After import, read the per-item errors array; fix and resubmit ONLY the rejected items (never resubmit ones that already imported). Report the lesson/cmid and anything you could not represent. Rules: - Never invent field names or values; re-read the spec if unsure. - Prefer the tts fields over uploading audio; the server generates that audio. - When a template and direct compose would both work, prefer the template unless the request needs verbatim fidelity or item-by-item control. |
Test it by asking you which courses you (the webservice user ) are enrolled in.
Accessing via Pure APIs (not MCP or GPT)
If you can not use the MCP or GPT options, e.g if you are using antigravity which supports neither, you can use the API directly and just let the agent figure out what it needs to do.
The URL to the API specification for the agent is at :
[your moodle url]/mod/minilesson/openapi.php
Open up your agent and instruct it to fetch the API spec from the openapi url (above) and then give it either the pre-generated web service user's web service token, or the web service user's username and password.
Putting it all together
A series of commands after that might look like:
- "fetch my courses"
- "create a new minilesson titled '[lesson name]'" in course [course name]
- "list the ai generate templates"
- "use [template name] to add items for ESL learners of CEFR level: A2 to [lesson name] using topic: [topic name] and vocabulary [some words].
- "Check every 30 seconds or so to see when its finished"
A Create-MiniLesson Skill
If you are using Claude Code, there is a skill attached to this page (create-minilesson.md) that you can put in your project's .claude/commands directory. It might work ok .. its a good start anyway,
Good Luck