An AI assistant for your course materials
Source:vignettes/articles/instructor-mcp.Rmd
instructor-mcp.Rmdmirtverse comes with an MCP server for instructors. MCP, the Model Context Protocol, is the standard way AI assistants connect to tools. Once you connect your assistant to the mirtverse server, it can open, edit and test the teaching materials in your course folder. You describe what you want in plain words, for example:
Add a question on local dependence to Lab 1, after the Q3 heatmap.
Use my midterm data (
data/midterm.csv) in the fairness lab instead of the numeracy test. The group variable iscampus.Here are my old lecture notes on the Rasch model, written with ltm. Turn them into a mirtverse chapter, but keep my examples.
The assistant reads your files, makes the change with the mirtverse instructor tools, runs the material to check that it still works, and tells you what it changed. It works with Claude (Desktop and Claude Code) and with OpenAI (Codex, the Agents SDK, and ChatGPT).
What the assistant can do
The server gives the assistant these tools. You never call them yourself; the assistant picks them.
| Task | Tools |
|---|---|
| See what is in your course |
course_overview, list_materials,
read_material
|
| Change files |
edit_material (part of a file),
write_material (new or whole file),
undo_last_change
|
| Build and change labs |
copy_lab, new_lab,
lab_outline, add_lab_section,
add_lab_exercise, add_lab_question,
remove_lab_section, swap_lab_data
|
| Chapters and notes |
copy_chapter, new_chapter,
swap_chapter_data
|
| Use your own data | describe_dataset |
| Bring in existing materials |
scan_material, translate_code (uses
mirtify()) |
| Get it right |
mirtverse_help (real function names and arguments),
guide (lab and chapter style, adapting materials, AI
content), check_material (runs the material) |
The lab and chapter tools use the functions of the instructor toolkit, so anything the assistant builds is the same as what you would build by hand.
It also offers four ready-made requests (MCP “prompts”), which appear
in clients that show them, such as the + menu in Claude
Desktop or / in Claude Code:
- Revise a teaching material: Give a file and say what to change.
- Adapt my materials to mirtverse: Give an existing lab, notes file or script.
- Build a lab on my data: Give a data file and a topic.
- Teach AI in measurement: Say what students should learn (for example “audit our essay-scoring engine”) and, optionally, give your item text or machine scores. The assistant picks a toolkit lab with the AI sections, a built-in AI lab or an AI chapter of the book, following the server’s guide to AI content.
Safety
- Only your course folder. The assistant can read and write files only inside the folder you choose. It cannot see the rest of your computer.
-
Every change can be undone. Before each change the
server backs up the files it touches (in a hidden
.mirtverse-mcpfolder inside your course). Ask the assistant to “undo the last change”, or to undo the last change to a particular file. - Your originals are kept. When adapting existing materials, the assistant writes the new version to a new file unless you ask it to replace the original.
-
Running code.
check_materialruns your materials’ R code in a separate R session on your computer, as you would when knitting them. It is on by default for desktop clients and off for ChatGPT (see below). - Your data. The assistant’s AI provider sees what the tools return: File contents, and summaries of datasets (column names, value ranges and counts, not the full data). Do not put identifiable student data in the course folder, or check your institution’s rules on AI tools first.
Set up
You need R with mirtverse installed (and learnr, for labs). Pick a
folder for your course, such as ~/courses/edpy507. If you
already used the instructor toolkit, use that course folder; otherwise
the assistant can set one up for you.
mv_mcp_config() prints the exact settings for your
computer, with the full path to R filled in:
library(mirtverse)
mv_mcp_config("~/courses/edpy507", client = "claude-desktop")Claude Desktop
- Run
mv_mcp_config("~/courses/edpy507", client = "claude-desktop"). - In Claude Desktop, open Settings > Developer > Edit
Config. This opens
claude_desktop_config.json. - Paste the
"mirtverse"entry inside"mcpServers"(create"mcpServers"if the file is empty), save, and restart Claude Desktop. - Start a new chat. The mirtverse tools appear under the tools icon. Try “What is in my course?”
The result looks like this (your paths will differ):
OpenAI Codex
Codex (the command-line tool and the IDE extension) reads
~/.codex/config.toml. Add the block that
mv_mcp_config(client = "codex") prints:
OpenAI Agents SDK
If you script with the OpenAI Agents SDK for Python,
mv_mcp_config(client = "openai-agents") prints a starting
point that connects an agent to the server with
MCPServerStdio.
ChatGPT
ChatGPT connects to servers by URL rather than starting them itself, so the server has to run over HTTP and be reachable from the internet. At the time of writing this needs ChatGPT’s developer mode (Settings > Apps & Connectors > Advanced), which is available on some plans only.
-
In R, start the server over HTTP:
mv_mcp_server("~/courses/edpy507", transport = "http", port = 8765)It prints a URL such as
http://127.0.0.1:8765/mcp/k3v9.... The random last part is a secret: Only people who know it can reach the server. Make the port reachable with a tunnel, for example
ngrok http 8765orcloudflared tunnel --url http://localhost:8765.In ChatGPT, create a connector with the tunnel address followed by
/mcp/<secret>and no authentication.
Over HTTP, check_material is off unless you start the
server with allow_run = TRUE, because anyone with the URL
could otherwise run R code on your computer. Stop the server (Esc or
Ctrl+C in R) when you are done.
Tips
- Start each conversation with the big picture: Which course, which students, what they already know. The assistant keeps your voice better when it knows your audience.
- Ask for a plan first for large changes (“tell me what you would change before you do it”).
-
Check its work. The assistant runs
check_materialafter every change, but you know your course: Preview a changed lab withlearnr::run_tutorial()or the Run Document button before your students see it. -
Let it look things up. If the assistant seems
unsure about a function, ask it to check
mirtverse_help.
For developers
The server is written in R with no extra dependencies and speaks MCP
(protocol versions 2024-11-05 to 2025-11-25) over stdio or Streamable
HTTP (JSON responses, no server-sent events). Tools that need the
instructor toolkit appear only when the installed mirtverse has it. See
?mv_mcp_server for all options.