# PupilBot for developers and AI agents

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

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.

## MCP server

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.

In Claude, add it under Settings → Connectors → Add custom connector and paste the URL. From a terminal:

- `claude mcp add --transport http pupilbot https://www.pupilbot.com/mcp`
- `codex mcp add pupilbot --url https://www.pupilbot.com/mcp`

## MCP tools

- **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.

The agent creates and reads; the practice session itself happens in the web app, the iPhone app, or the Telegram bot.

## MCP manifests

- https://www.pupilbot.com/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.
- https://www.pupilbot.com/.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 spec

https://www.pupilbot.com/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.

## OAuth 2.1

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, and refresh tokens rotate.
- `POST /mcp` — the resource itself. Without a valid token it answers 401 with a `WWW-Authenticate` challenge naming the metadata document below.

Discovery: https://www.pupilbot.com/.well-known/oauth-authorization-server (RFC 8414) and https://www.pupilbot.com/.well-known/oauth-protected-resource (RFC 9728). Both are also served with a `/mcp` suffix, for clients that insert the resource path.

## Agent files

- https://www.pupilbot.com/llms.txt — the agent brief: what PupilBot is, when to reach for it, how to call it, and what not to claim about it.
- https://www.pupilbot.com/llms-full.txt — that brief plus the full text of every content page, inlined, so one fetch stands alone.
- Markdown twins — every content page is also served at its path with a `.md` suffix: https://www.pupilbot.com/index.md, https://www.pupilbot.com/support.md, https://www.pupilbot.com/developers.md. Twins are English-only; a locale-prefixed twin URL redirects to the bare one.
- https://www.pupilbot.com/sitemap-agents.xml — the whole agent surface as a sitemap, advertised in https://www.pupilbot.com/robots.txt alongside the HTML sitemap.

## Markdown content negotiation

The landing page, Support and this page 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.

`curl -H "Accept: text/markdown" https://www.pupilbot.com/`

## What is not public

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.

## Contact

Questions about any of this: support@pupilbot.com.