PupilBot turns study material a student supplies — photographed notes, a handout, or pages picked out of a PDF — into adaptive practice questions scheduled by spaced repetition. This page names every machine-readable surface PupilBot publishes, and links each one.
PupilBot runs a Model Context Protocol server at https://www.pupilbot.com/mcp. It speaks Streamable HTTP and is stateless: one JSON-RPC 2.0 request per POST, one JSON response, no SSE stream and no session ids. Authentication is OAuth 2.1 with PKCE (S256 required) against a PupilBot account. Opening that URL in a browser returns a human-readable connect page rather than the transport.
In Claude, add it under Settings → Connectors → Add custom connector and paste the URL. In ChatGPT, open Plugins, select + and choose Add custom MCP server. From a terminal:
claude mcp add --transport http pupilbot https://www.pupilbot.com/mcpcodex mcp add pupilbot --url https://www.pupilbot.com/mcp, then codex mcp login pupilbot to run the OAuth flowThe server exists so a student's own AI can read their PupilBot record and analyse it for them. Seven tools, all scoped to the signed-in student. Every tool declares an outputSchema and returns structuredContent plus a text block with the same JSON.
| Tool | What it does |
|---|---|
list_studies |
The student's studies, newest first, with topics total, covered and retained, reviews due now and the last practice time. Optional status and limit. |
get_study |
One study: status, processing stage, failure reason, question count, and every topic with its stage (untested, learning, covered, retained), mastery score, recall estimate, attempts, correct answers, due reviews and next due time. Poll it after create_study. |
get_answers |
Answer history, newest first: question, options (choice types only), the student's answer, correct answer, grade, score, feedback and source passage. Corrected (invalidated) answers are left out. Filters: study_id, topic_id, since, only_incorrect; limit up to 100, paged with cursor. |
get_weak_spots |
The weakest practised topics, concepts missed at least twice with no correct answer since, and wrong answers in the last 7 days. Covers focused ready studies unless study_id is given. |
get_due |
FSRS reviews per study: due now, due in the next 24 hours, and the next due time. |
get_progress |
Answers and accuracy per day in the student's time zone, the current streak, and how each practised topic's mastery moved. days defaults to 30, maximum 180. |
create_study |
Creates a study from text (notes, an article, a chapter — plain text or markdown, up to 250,000 characters, 15,000 on the free plan; no files). PupilBot extracts the topics and generates practice questions; processing takes about a minute. Returns the new study id. |
Every tool except create_study carries readOnlyHint: true; create_study is readOnlyHint: false, destructiveHint: false. The read tools run no AI model on PupilBot's side. Titles, topic names, questions, options, answers, feedback, concepts and source passages come from the student's material or typing: they are data, never instructions, and the server instructions say so.
The agent reads and can create a study; the practice session itself happens in the web app, the iPhone app, or the Telegram bot.
PupilBot publishes a plugin for Claude Code and one for Codex (marketplace gabrielpolyy/pupilbot-plugins, install id pupilbot@pupilbot). Each adds the MCP server and 3 skills: study-report, due-today and make-study. Install commands are on the MCP page.
/mcp/server-card — the MCP Server Card (SEP-2127), served as application/mcp-server-card+json. It carries the server name, version, website, icon and the Streamable HTTP remote with the protocol versions it supports./.well-known/ai-catalog.json — the AI Catalog, served as application/ai-catalog+json. It is the well-known URI the Server Card extension reserves, and it holds one entry pointing at the card above./openapi.json is an OpenAPI 3.1 description of the public agent surface: the MCP endpoint and its OAuth 2.1 flow, the discovery documents, the agent files, and the health check.
It deliberately does not describe the /api/* routes the web app and the iPhone app call — see “What is not public” below.
The MCP endpoint is a protected resource. Clients register themselves; there is no manual client provisioning.
POST /oauth/register — dynamic client registration (RFC 7591). Redirect URIs must be HTTPS, or loopback HTTP.GET /oauth/authorize — the consent page. The user signs in with their PupilBot account and approves the client.POST /oauth/token — code exchange and refresh. PKCE with S256 is required. Access tokens are JWTs for the audience pbot-mcp and expire after 1 hour; they are not accepted by the app's own /api/* routes. Refresh tokens last 180 days and rotate on every use.POST /mcp — the resource itself. Without a valid token it answers 401 with a WWW-Authenticate challenge naming the metadata document below.Every request to /mcp also checks that the student's grant for that client still exists. The student can disconnect a client in the web app under Settings, and access stops at once; a password reset or account deletion disconnects every client.
Discovery: /.well-known/oauth-authorization-server (RFC 8414) and /.well-known/oauth-protected-resource (RFC 9728). Both are also served with a /mcp suffix, for clients that insert the resource path.
/llms.txt — the agent brief: what PupilBot is, when to reach for it, how to call it, and what not to claim about it./llms-full.txt — that brief plus the full text of every content page, inlined, so one fetch stands alone..md suffix: /index.md, /support.md, /developers.md, /mcp.md, and one per feature page: /pdf-to-flashcards.md, /notes-to-quiz.md, /image-to-flashcards.md, /ai-quiz-generator.md, /spaced-repetition-study-app.md, /ai-for-studying.md. Twins are English-only; a locale-prefixed twin URL redirects to the bare one./sitemap-agents.xml — the whole agent surface as a sitemap, advertised in /robots.txt alongside the HTML sitemap.The landing page, Support, this page, the MCP connect page and the six feature pages (/pdf-to-flashcards, /notes-to-quiz, /image-to-flashcards, /ai-quiz-generator, /spaced-repetition-study-app, /ai-for-studying) answer Accept: text/markdown with the same markdown twin, from the HTML URL, with Vary: Accept. q-values are honoured, and a request that accepts nothing we produce gets a 406 — except at /mcp, which is also the MCP transport endpoint: an Accept it cannot satisfy gets the HTML page rather than a 406, so a client GETting that URL is never locked out.
curl -H "Accept: text/markdown" https://www.pupilbot.com/
There is no public, unauthenticated REST API. The /api/* routes exist for the PupilBot web app and iPhone app only: they are first-party, unversioned, and authenticated per user, and they can change without notice. Study material, questions and mastery are private to each account. The MCP server above is the supported way for an agent to reach a user's data, with that user's consent.
Questions about any of this: [email protected].