Quiz MCP is a small ChatGPT App server that renders interactive quizzes inside ChatGPT.
It runs as a Cloudflare Worker. ChatGPT sends quiz questions to the Worker, the Worker checks and shuffles them, and the widget shows the quiz with scoring, explanations, review, study mode, retakes, and themes.
- Interactive multiple-choice, true/false, matching, and sorting quizzes
- Single-answer and multiple-answer questions
- Drag-and-drop matching and sorting with tap/click fallbacks
- Immediate feedback after each answer
- Final score screen with 1000-point question scoring and partial credit
- Review, missed-only review, flagged questions, and learn mode
- Built-in themes that persist in the browser when possible
- No database required
- No user progress stored on the server
For most people, use No authentication.
This app does not read private files, call paid APIs, store user data, or change anything outside the quiz widget. ChatGPT app setup is also much simpler with no auth.
No authentication means the deployed MCP endpoint is publicly reachable. Use it only for quizzes and content that are safe to expose publicly.
Use OAuth only if you are publishing a private app for a school, company, or closed group. OAuth requires a real identity provider.
Use the admin password mode only for your own testing. ChatGPT may not offer the header-based auth option needed for it.
Install the current LTS version from:
https://nodejs.org
After installing, open a new terminal.
Clone the repo or download it as a ZIP from GitHub.
Then open a terminal in the project folder.
On macOS or Linux:
./deploy.shOn Windows PowerShell:
.\deploy.ps1The script will:
- check for Node and npm
- install project dependencies
- install Wrangler
- help you log in to Cloudflare
- ask for an auth mode
- deploy the Worker
- print the MCP URL to use in ChatGPT
Choose none when it asks for auth mode unless you already know you need OAuth.
- Open ChatGPT settings.
- Go to Apps & Connectors.
- Enable Developer Mode if needed.
- Create a new app.
- Choose Server URL.
- Paste the MCP URL printed by the deploy script.
The URL should look like this:
https://your-worker.your-account.workers.dev/mcp
For authentication, choose No authentication if you deployed with auth mode none.
After changing code or metadata, refresh the app in ChatGPT settings so ChatGPT reloads the latest tool description and widget template.
If you prefer commands:
npm install
npm test
npm run typecheck
npm run deployThe deploy command uses Wrangler and minifies the Worker before upload.
The checked-in wrangler.jsonc is public/no-auth and intentionally leaves deployment-specific URLs blank. On production HTTPS, the Worker derives widget metadata from the incoming request origin. Keep personal workers.dev URLs in local notes or ignored deploy state, not in git.
Start a local Worker:
npm run devRun the smoke test in another terminal:
npm run smokeThe local smoke test checks:
- MCP initialize
- tool listing
- widget resource reading
- quiz rendering
- no-auth Apps SDK metadata
- the current widget template URI
- empty widget connect/resource domains
- the direct widget route CSP
- hidden OAuth metadata in no-auth mode
The root page (/) and demo preview page (/preview) are intentionally not served. This repo is meant to expose the MCP endpoint, not a public website.
The widget vendors KaTeX 0.17.0 into src/vendor/katex.ts with npm run vendor:katex and embeds it inline. No CDN or auto-updating math script is loaded at runtime.
Tool name:
render_inline_quiz
Example input:
{
"title": "Sample quiz",
"targetGradePercent": 80,
"theme": "aurora",
"questions": [
{
"prompt": "Which number is prime?",
"type": "multiple_choice",
"explanation": "A prime number has exactly two positive factors.",
"answers": [
{ "text": "2", "correct": true, "explanation": "2 is prime." },
{ "text": "4", "correct": false, "explanation": "4 is divisible by 2." }
]
},
{
"prompt": "Match each country to its capital.",
"type": "matching",
"pairs": [
{ "prompt": "France", "match": "Paris" },
{ "prompt": "Italy", "match": "Rome" }
]
},
{
"prompt": "Sort the workflow from first to last.",
"type": "sorting",
"items": [
{ "text": "Plan" },
{ "text": "Build" },
{ "text": "Ship" }
]
}
]
}Compact input for long quizzes is also accepted:
{
"title": "Sample quiz",
"questions": [
{
"q": "Which number is prime?",
"type": "mc",
"a": [
{ "t": "2", "c": true },
{ "t": "4" }
]
},
{
"q": "Match each country to its capital.",
"type": "match",
"p": [
{ "t": "France", "m": "Paris" },
{ "t": "Italy", "m": "Rome" }
]
},
{
"q": "Sort the workflow from first to last.",
"type": "sort",
"i": [
{ "t": "Plan" },
{ "t": "Build" },
{ "t": "Ship" }
]
}
]
}Rules:
- A quiz can have 1 to 500 questions.
- Each question can have 2 to 6 answers.
multiple_choicequestions need at least one correct answer.multiple_choicequestions may have more than one correct answer.true_falsequestions need exactly two answers and exactly one correct answer.matchingquestions need 2 to 10 unique pairs. Usepairsor compactp; each pair usesprompt/matchor compactt/m.sortingquestions need 2 to 10 unique items in the correct order. Useitemsor compacti; each item usestextor compactt.- Matching and sorting support partial credit. The widget score adds 1000 points for a fully correct question, a proportional amount for partial answers, and 0 for fully wrong answers.
- For large quizzes, prefer compact aliases:
q/afor question prompt/answers,t/c/efor answer text/correct/explanation,pwitht/mfor matching,iwithtfor sorting, andmc/tf/match/sortfor type values. correctandccan be omitted for false answers.targetGradePercentis optional and defaults to 70.themeis optional. Available themes areaurora,paper,sakura,ember,circuit, andharbor.- Question text, answer text, and explanations can include LaTeX math such as
$x = 2$. - Keep answer choices fair and non-signaling: similar length, detail, specificity, tone, grammar, and formatting; distractors should be plausible instead of obviously weaker than the correct answer.
- Do not depend on answer letters. The server shuffles answer order.
Default and recommended.
"AUTH_MODE": "none"Use this for public quiz widgets and normal ChatGPT app setup. Do not use this mode for private course material, internal exams, or anything that requires access control.
Use this for private deployments with a real OAuth provider.
You must provide:
- issuer URL
- authorization server URL
- JWKS URL
- audience or resource
- scopes
The Worker validates bearer tokens before protected tool calls.
Use this only for private testing.
The guided deploy script generates a random password, saves it as a Cloudflare Worker secret, writes .quizmcp-admin.json, and makes unauthenticated routes return 404.
Do not commit .quizmcp-admin.json. It is already ignored by git.
- The Worker stores no quiz attempts, answers, or user progress.
- Widget progress is saved client-side only, using compact browser storage, a cookie fallback, and host private widget state when available.
- The answer key is sent only as widget metadata, not in model-visible quiz content.
- The widget uses
textContentinstead ofinnerHTMLfor quiz text. - Requests, batch size, question count, string length, and total quiz text are limited.
- Control characters and bidirectional override characters are stripped from quiz text.
- The widget does not load external scripts, fonts, frames, or images.
- The widget's LaTeX renderer is vendored and pinned instead of loaded from a CDN.
- The app serves no public root HTML page.
- Secrets belong in Cloudflare secrets or local ignored files, never in git.
- Do not put
ADMIN_BEARER_TOKENor provider secrets inwrangler.jsoncvars. - Do not commit personal workers.dev URLs. Leave
PUBLIC_BASE_URLandWIDGET_DOMAINblank unless you are committing a generic placeholder. - The guided deploy preserves an existing private auth mode as the default choice, so pressing Enter will not silently switch an OAuth/admin deployment back to public no-auth.
- The guided deploy rejects unknown
AUTH_MODEvalues instead of guessing.
src/mcp.ts- MCP server and HTTP routessrc/quiz.ts- quiz validation and shufflingsrc/widget.ts- inline widget HTML, CSS, and JavaScriptscripts/deploy.mjs- guided deploy scriptscripts/smoke.mjs- basic MCP smoke testtest/- unit tests
npm test
npm run typecheck
npm run deploy
npm run deploy:interactiveMIT


