# PupilBot MCP server

Source: https://www.pupilbot.com/mcp
Full agent brief: https://www.pupilbot.com/llms.txt

https://www.pupilbot.com/mcp is a Model Context Protocol endpoint, not a page to read. Connect it to Claude, ChatGPT, Codex or any other MCP client, and that assistant can turn your notes into PupilBot studies and read back how well you know them.

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. The practising happens in the web app (https://www.pupilbot.com), the iPhone app or the Telegram bot; the assistant creates and reads.

## Connect it

The server URL is https://www.pupilbot.com/mcp. It needs a PupilBot account: the first connection opens a consent page where you sign in and approve the client. No account yet? Create one at https://www.pupilbot.com/signup first.

- **Claude (web, desktop or mobile)** — Settings → Connectors → Add custom connector, then paste the URL.
- **ChatGPT** — a custom MCP endpoint needs developer mode turned on first. The menu path moves between ChatGPT releases, so follow OpenAI's connect guide (https://developers.openai.com/plugins/deploy/connect-chatgpt) for the current steps; which plans expose it is ChatGPT's call, not ours.
- **Claude Code** — `claude mcp add --transport http pupilbot https://www.pupilbot.com/mcp`
- **Codex CLI** — `codex mcp add pupilbot --url https://www.pupilbot.com/mcp`, then `codex mcp login pupilbot` — adding an OAuth-protected server does not start the sign-in, the second command does.
- **Anything else** — any Streamable HTTP MCP client, pointed at the URL above. There is no manual client provisioning: clients register themselves.

## What your assistant can do

- **create_study** — creates a study from text (notes, an article, a chapter — plain text or markdown, up to 400,000 characters). PupilBot extracts the topics and generates practice questions; processing takes about a minute. Returns the new study id.
- **get_study_status** — checks a study's processing status: `uploaded`/`processing` means not ready yet, `ready` means the questions exist, `failed` means processing did not finish.
- **list_studies** — lists the user's studies, newest first, optionally filtered by status.
- **get_mastery** — without a study id, a mastery summary for every ready study. With one, per-topic mastery for that study: score 0–1, attempts, streaks and next review.

## Things to ask

- "Turn these lecture notes into a PupilBot study."
- "Is my organic chemistry study ready to practise yet?"
- "Which topics am I weakest on across all my studies?"
- "List my studies and tell me what is due for review."

## Authentication

The endpoint is an OAuth 2.1 protected resource. PKCE with `S256` is required, refresh tokens rotate, and clients register themselves (RFC 7591) — so most MCP clients run the whole flow on their own once you approve the consent screen.

Discovery: https://www.pupilbot.com/.well-known/oauth-authorization-server (RFC 8414) and https://www.pupilbot.com/.well-known/oauth-protected-resource (RFC 9728). An unauthenticated `POST` answers 401 with a `WWW-Authenticate` challenge naming the second one.

Your studies, questions and mastery are private to your account. An assistant reaches them only with a token you approved.

## Transport

Streamable HTTP, stateless: one JSON-RPC 2.0 request per `POST`, one JSON response. No SSE stream, no session ids, no JSON-RPC batching. A `GET` that asks for `text/event-stream`, and any `DELETE`, answer `405` — which is what tells a client to fall back to plain POSTs; a `GET` that does not ask for the stream gets this page.

## More

- https://www.pupilbot.com/developers — developer and agent documentation: every machine-readable surface PupilBot publishes.
- https://www.pupilbot.com/openapi.json — an OpenAPI 3.1 description of this endpoint and its OAuth flow.
- https://www.pupilbot.com/mcp/server-card and https://www.pupilbot.com/.well-known/ai-catalog.json — pre-connection discovery (MCP Server Card, SEP-2127).
- Questions: support@pupilbot.com.