Skip to main content
Pitchrise

Documentation

Instructor quickstart and MCP

Create the class, share a join link, and add credits. Then connect a chat client to the MCP server if you want to run those same steps from a conversation.

Instructor quickstart

Run a free pilot cohort opens a sandbox institution and makes you the org admin. A sandbox starts with 5 seats and lasts 90 days. No card is required to open it. Then:

  1. Step 1

    Create a class

    Open Classes and choose Create Class. An org admin or a school admin can create a class. Name it, pick the school, and set the instructor. A new institution includes a default school. Choose General when the cohort is not a Basics subject.

    In chat, the matching tool is educator_create_class.

    Open Classes

  2. Step 2

    Share a join link

    Open Students and create a student invite link. Share that URL. Anyone who signs up or signs in with it joins the institution as a student. An org admin creates the link. Turning the link off stops new people from using it. People who already joined stay enrolled.

    In chat, the matching tool is educator_create_join_link.

    Open Students

  3. Step 3

    Add credits

    Open Plan and Billing. Add funds to the institution pool, or move credits from a personal balance. Students and teachers cannot use AI features until that pool has a balance.

    In chat, the matching tool is educator_create_credit_checkout.

    Open Plan and Billing

Connect with OAuth 2.0

The MCP server is Streamable HTTP. Clients that speak MCP OAuth discover the authorization server from the protected-resource metadata, then sign the person in through the browser.

Server URL

https://pitchrise.ludwitt.com/api/mcp

  1. Point the client at the server URL above.
  2. The client reads protected-resource metadata, then authorization server metadata.
  3. The client registers at the registration endpoint as a public client, or presents an HTTPS client ID metadata document.
  4. The person signs in at the authorization endpoint and approves scopes. The response type is code. PKCE is required, using S256.
  5. The client exchanges the code at the token endpoint with the PKCE verifier. Grant types are authorization_code and refresh_token. The token endpoint auth method is none.
  6. Later calls send Authorization: Bearer with the access token.
MCP OAuth endpoints
PieceURL
Serverhttps://pitchrise.ludwitt.com/api/mcp
Protected resource metadatahttps://pitchrise.ludwitt.com/.well-known/oauth-protected-resource
Authorization server metadatahttps://pitchrise.ludwitt.com/.well-known/oauth-authorization-server
Authorization endpointhttps://pitchrise.ludwitt.com/oauth/mcp/authorize
Token endpointhttps://pitchrise.ludwitt.com/api/mcp/oauth/token
Registration endpointhttps://pitchrise.ludwitt.com/api/mcp/oauth/register

Token lifetimes

  • Authorization code: 5 minutes
  • Access token: 1 hour
  • Refresh token: 30 days

Scopes

A new OAuth client asks for learner tools and class management unless it requests more. That default scope string is basics:read basics:write alc:read classes:read classes:write. Institution scopes are requested on their own. Re-authorize when a tool returns missing_scope.

  • basics:read — Read Basics progress and current problems
  • basics:write — Submit Basics answers and update learning progress
  • alc:read — Read ALC (Developer Training) path and step progress
  • classes:read — List institutions, schools, classes, and rosters the educator can see
  • classes:write — Create and update classes, and enroll or remove class members
  • orgs:write — Create an institution and its schools
  • invites:read — List pending institution invites and student invite links
  • invites:write — Invite people by email, create student invite links, and revoke or resend invites
  • billing:read — Read an institution credit pool, deposits, and checkout status
  • billing:write — Create institution payment links and set per-student credit caps
  • progress:read — Read class and student learning progress

API key fallback

A client without OAuth can send a developer key, pk_live_ or pk_test_, as Authorization: Bearer or X-API-Key. An empty API-key scope list grants every scope except billing:write. Create a key at https://pitchrise.ludwitt.com/account/api-keys.

Tools

33 tools. Names and descriptions are the ones the server registers.

Learner

  • basics_get_progress

    Basics: Get Progress

    Start (or continue) an in-chat Ludwitt Coach session. Returns math, reading, latin, greek, and logic progress for the authenticated learner. Prefer this over sending the learner to the website. Requires basics:read (or empty scopes).

  • basics_get_current_problems

    Basics: Get Current Problems

    Fetch the next adaptive Basics item(s) for in-chat practice. Subjects: math, reading, latin, greek, logic, or both (math+reading). Payloads omit answers/spoilers — present them in chat, then grade with basics_check_answer. Writing is not supported (no adaptive loop). Requires basics:read.

  • basics_check_answer

    Basics: Check Answer

    Grade a learner answer from chat and update progress (same engines as /api/basics/*). Subjects: math, reading, latin, greek, logic. Response may include a reveal block with answers/explanations for coaching after the attempt. Requires basics:write.

  • alc_get_progress

    ALC: Get Progress

    Read Developer Training (ALC) path selection, current step, and completion flags so a coach knows where the learner is. Requires alc:read.

Classes

  • educator_list_orgs

    Educator: List institutions

    List institutions where the signed-in user is an org-admin, school-admin, or instructor. Includes self.userId for instructorId "me". Requires classes:read.

  • educator_list_schools

    Educator: List schools

    List schools in an institution that this educator can see. Requires classes:read.

  • educator_list_classes

    Educator: List classes

    List active classes this educator can see in an institution. Org-admins see every class; school-admins see their schools; instructors see classes they teach. Requires classes:read.

  • educator_get_class

    Educator: Get class

    Read one class and whether this user can edit it or change its roster. Requires classes:read.

  • educator_list_roster

    Educator: List class roster

    List students and co-teachers on a class, with name and email when the institution membership has them. Requires classes:read.

  • educator_list_members

    Educator: List institution members

    List people already in the institution so they can be enrolled in a class. Optional role filter. Requires classes:read.

  • educator_create_class

    Educator: Create class

    Create a class in a school. Org-admin or school-admin only. instructorId is a user id, or "me" for the signed-in user. Requires classes:write.

  • educator_update_class

    Educator: Update class

    Change a class name, period, subject, grade, size, or primary instructor. Org-admin or school-admin only. Pass null to clear period, subject, or gradeLevel. Requires classes:write.

  • educator_archive_class

    Educator: Archive class

    Deactivate a class. Org-admin or school-admin only. Requires classes:write.

  • educator_enroll_members

    Educator: Enroll class members

    Add existing institution members to a class by userId or email. Role is student (default) or co-teacher. People who are not members yet need educator_invite_members. Requires classes:write.

  • educator_remove_member

    Educator: Remove class member

    Remove one person from a class roster. The class instructor, a school-admin, or an org-admin may do this. Requires classes:write.

Institution and invites

  • educator_create_org

    Educator: Create institution

    Create a sandbox institution for the signed-in user, who becomes org-admin, plus a default school. Requires a verified email and orgs:write. K-12 requires attestsAuthority: true. One create per 24 hours, three lifetime.

  • educator_create_school

    Educator: Create school

    Add a school to an institution. Org-admin only. Requires orgs:write. Idempotent for the same code.

  • account_resend_verification

    Account: Resend verification email

    Email a verification link to the signed-in user. Does not return the link. Requires orgs:write.

  • educator_invite_members

    Educator: Invite members

    Invite people by email. Org-admins may invite students, instructors, or school-admins. School-admins and instructors may invite students into a class they manage. Never returns a set-password link. Requires invites:write.

  • educator_list_invites

    Educator: List pending invites

    List pending invites. Org-admins see all. Other educators see invites they sent. Requires invites:read.

  • educator_revoke_invite

    Educator: Revoke invite

    Revoke a pending invite. Org-admin or the original inviter. Requires invites:write.

  • educator_resend_invite

    Educator: Resend invite

    Email the setup link again. Does not return the link. At most 3 times per invite per day. Org-admin only. Requires invites:write.

  • educator_create_join_link

    Educator: Create student invite link

    Create a shareable link. Anyone who signs up or signs in with it joins this institution as a student. Returns the URL. Org-admin only. Requires invites:write and a verified email. Does not email anyone.

  • educator_list_join_links

    Educator: List student invite links

    List student invite links for an institution, including ones that are off, expired, or full. Org-admin only. Requires invites:read.

  • educator_revoke_join_link

    Educator: Turn off student invite link

    Stop a student invite link from enrolling anyone else. People who already joined stay enrolled. Org-admin only. Requires invites:write.

Billing and progress

  • educator_transfer_personal_credits

    Educator: Transfer personal credits

    Move credits from the signed-in user personal balance into this institution pool. Org-admin or school-admin. Does not charge a card. Requires billing:write. amountCents is between 500 and 50000.

  • educator_get_credits

    Educator: Get credit pool

    Read the institution credit balance, recent deposits, and whether org credits are enabled. Org-admin only. Requires billing:read.

  • educator_create_credit_checkout

    Educator: Create credit checkout

    Create a Stripe Checkout link for an institution credit deposit. The human pays in the browser. Does not take card details. Org-admin only. Requires billing:write, which is never implied by an empty API-key scope list.

  • educator_get_checkout_status

    Educator: Get checkout status

    Poll a checkout session until credited is true. Rejects a session that belongs to another institution. Requires billing:read.

  • educator_set_student_cap

    Educator: Set student credit cap

    Set or clear one student cap on the institution pool. Org-admin only. Requires billing:write.

  • educator_get_class_progress

    Educator: Get class progress

    Class aggregate and per-student Basics progress for a class this educator can see. Requires progress:read.

  • educator_get_student_progress

    Educator: Get student progress

    One student progress record. Org-admin, or an educator who can see a class that contains the student. Requires progress:read.

  • educator_needs_attention

    Educator: Needs attention

    Pending invites, seat pressure, and other institution follow-ups. Org-admin or school-admin. Requires progress:read.