One URL, standard OAuth, no SDK. This page walks through every supported path — Claude, ChatGPT, Cursor, and machine-to-machine for your own agents — plus the full tool reference and what each error means.
The complete integration spec — every tool, the OAuth flows, the data model, and exactly how learner progress works — as one Markdown file. Copy it straight into Claude Code, Cursor, or any coding agent and let it wire up the connector for you.
The complete integration spec as Markdown — drop it into Claude Code, Cursor, or any coding agent as context and it can wire up the connector, call the right tools, and key learner progress to our stable lesson ids.
Access is licensed to institutions. If your school, district, university, or company doesn’t hold a license yet, talk to us — evaluation licenses cover a single subject so you can try it first.
Sign-in uses your scolavo.com account (email or Google). We add your account’s email to your organization’s license during onboarding — after that, your access simply follows your sign-in, on every AI host.
https://mcp.scolavo.com/mcpEverything below connects to this endpoint. It speaks the Model Context Protocol (MCP) over HTTPS with standard OAuth discovery — unauthenticated calls return an OAuth challenge that tells your host exactly how to sign you in.
In Claude (web or desktop): Settings → Connectors → Add custom connector.
Name it “Scolavo” and paste https://mcp.scolavo.com/mcp. Claude reads the endpoint’s OAuth discovery documents automatically — there is no API key to enter.
Claude opens the Scolavo sign-in page. Use the account email on your organization’s license (email or Google). Approve, and you’re connected.
Ask Claude anything against the curriculum — “Find the Scolavo lesson on photosynthesis and build me a study guide from its transcript.” Claude picks the right tools; every answer carries a citation link back to scolavo.com. In Claude Code, add it withclaude mcp add --transport http scolavo https://mcp.scolavo.com/mcp.
Settings → Connectors → Advanced → Developer mode (workspace admins may need to allow connectors first).
Create a connector named “Scolavo” with the MCP server URLhttps://mcp.scolavo.com/mcp and OAuth authentication, then complete the same one-time sign-in.
The server implements ChatGPT’s search /fetch contract, so deep-research reports can quote and cite Scolavo lessons as sources.
Any MCP-compatible host works the same way: give it the URL, let OAuth discovery do the rest. For Cursor, add this to ~/.cursor/mcp.json (or via Settings → MCP → Add server):
{
"mcpServers": {
"scolavo": { "url": "https://mcp.scolavo.com/mcp" }
}
}Cursor prompts for the same one-time sign-in the first time a tool is called.
For headless systems — RAG indexers, nightly exports, internal chatbots — we issue your organization a confidential OAuth client (a client id + secret; the secret is shown once at issuance). No user sign-in involved.
Standard client_credentials against the token endpoint. Tokens are valid for 15 minutes — request a fresh one per batch.
JSON-RPC 2.0 over HTTPS. Send both Authorization: Bearerand Accept: application/json, text/event-stream.
# 1) token (client_credentials, HTTP Basic auth with your client id + secret)
TOKEN=$(curl -s -X POST 'https://scolavo-auth.auth.us-east-1.amazoncognito.com/oauth2/token' \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d 'grant_type=client_credentials' | jq -r .access_token)
# 2) call a tool
curl -s -X POST 'https://mcp.scolavo.com/mcp' \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"list_subjects","arguments":{}}}'Or point any MCP client library at the endpoint with the same bearer token. Clients can be revoked by us at any time; revocation lands within one token lifetime.
Five groups, twenty-three tools — browse and discover, read and tutor, the learning graph, media and export, and test prep — every one scoped to your organization’s content grants; get_license_status shows exactly what your license covers.
list_tiersThe curriculum tiers with subject counts each — the lightest way to see what exists before drilling in.
list_subjectsEvery subject in your license, with class counts and media coverage. Paged.
get_catalogThe entire licensed catalog in one call, grouped by tier — metadata only, no paging needed.
get_subject_outlineOrdered class list for one licensed subject with per-class video / narration / transcript flags.
search_contentContent search over titles, subtitles, card labels, key points, and quiz items (not full body text). Returns lessonId hits.
get_lessonOne class-lesson as structured text. Lean by default; opt into quiz / inlineChecks / narrationText / media via include[].
get_lesson_contextThe full AI-tutor bundle for one class in a single call — cards, quiz, hints, a worked example, common mistakes, and the adjacent lessons.
get_lesson_summaryA lightweight review summary — key points, key terms, and the quiz — for spaced review without pulling the full lesson.
get_quizEnd-of-class quiz plus mid-lesson checks, with hints and rationale.
get_next_lessonMetadata for the next class in the same subject, so your AI never has to guess the class number.
get_prev_lessonMetadata for the previous class in the same subject.
search_subjectsFind which subjects cover a concept, ranked by how many lessons match.
get_learning_pathThe ordered study sequence to reach a goal subject — prerequisites first — with difficulty and estimated hours at every step.
get_conceptTrace one concept across the curriculum: every lesson that teaches it, its prerequisite subjects, and what it leads to next.
list_lesson_mediaEvery video, narration audio, and illustration attached to a lesson.
get_download_urlMint a short-lived (≤15 min) signed link to stream or download one asset.
export_classOne class as a bundle: lesson JSON, transcript, media manifest.
export_subjectA whole subject or Topic in one call — every class, transcript, and media link. Bundles are stamped to your organization.
list_testprep_catalogThe four original practice-test banks: Digital SAT, ACT, PSAT/NMSQT, CAASPP.
get_testprep_itemsItems from one bank, filterable by section.
get_license_statusYour organization’s tier, content grants, quota usage, and renewal date.
searchThe ChatGPT deep-research search half — returns citable {id, title, url} hits.
fetchThe ChatGPT deep-research fetch half — full lesson text by id, with a citation URL back to scolavo.com.
The token you pass is a standard signed JWT. On the interactive paths the learner signs in through Scolavo, so the token carries both the organization and the learner — which opens two ways to handle progress. You choose per license.
When your learners sign in with Scolavo identity, we record their progress in the same backend that powers scolavo.com — so progress through the connector and on the site is the same record, with nothing for you to build. Progress tools sit behind a dedicated progress scope, provisioned per license. This is the turnkey path most partners choose.
Bring your own identity or LMS and keep progress entirely on your side, using the connector as a pure content pipe. Key your records to Scolavo’s stable lessonId and card/quiz ids, sequence with get_learning_path, and no student data reaches Scolavo through the connector.
Both models use the standard Cognito access token in the Authorization header — an interactive (learner-scoped) token for Scolavo-hosted progress, or the org token for a content-only integration. Machine-to-machine tokens carry no learner, so progress tools need a learner-scoped token.
The full spec covers both models — the learner-scoped token flow, theprogress scope, and the data-processing note for Scolavo-hosted progress. Tell us which fits at licensing@scolavo.com.
Denials are structured business errors, not opaque failures — each carries a code your AI can read back to you.
401 UnauthorizedNo or expired token. Interactive hosts refresh automatically — reconnect if prompted. Machine tokens live 15 minutes; request a new one.
NO_ORGANIZATIONYour account isn’t linked to a licensed organization yet. Write to licensing@scolavo.com.
LICENSE_REQUIREDYour organization hasn’t accepted the current license agreement (ECLA). Your admin signs once; access opens on the next call.
TIER_NOT_LICENSED / CONTENT_NOT_GRANTEDThe subject is outside your organization’s content grants. get_license_status shows exactly what you’re licensed for.
LICENSE_EXPIRED / ORG_SUSPENDEDThe license lapsed or was suspended. Renewal or reinstatement takes effect on the very next call.
QUOTA_EXCEEDED / EXPORT_LIMIT / RATE_LIMITEDA monthly quota or hourly rate limit was hit. get_license_status shows remaining allowances; limits reset on their natural boundary.
Still stuck? Write to licensing@scolavo.com — include the error code and roughly when the call was made, and we can trace it on our side. Your security team can also probe the endpoint before anything is signed: unauthenticated calls return a standard OAuth challenge, and both discovery documents are public.
Institutional licensing is annual and PO-friendly, with single-subject evaluation licenses to start. A person replies with a quote and the license agreement — no demo call required.