MCP server

Aceversity's Model Context Protocol server at https://api.aceversity.com/mcp exposes every API operation as a tool for Claude and other MCP clients.
URL https://api.aceversity.com/mcp
Transport Streamable HTTP (POST JSON-RPC, JSON responses; no SSE stream or session needed)
Protocol versions 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05 (negotiated in initialize)
Auth OAuth 2.1 (discovered from the 401 challenge) or an API key as Authorization: Bearer ace_sk_…
Capabilities tools

The tools are generated from the same definitions as the REST API and openapi.json, so names, inputs and outputs always match the reference. Each tool returns its JSON result both as structuredContent (validated against the tool's outputSchema) and as text.

Tools

Tool What it does Scope Hints
get_me Profile, today's date, membership, credential scopes read read-only
get_agenda Items and unfinished milestones due in the next N days read read-only
list_courses The member's courses read read-only
get_course One course, next 5 items, optional syllabus text read read-only
create_course Add a course write
update_course Change course fields write idempotent
delete_course Delete a course and everything in it write destructive
list_items Deadlines, filterable by course/kind/date read read-only
get_item One deadline read read-only
create_item Add an exam/quiz/assignment/lab/paper/project write
update_item Rename, re-kind or move a deadline write idempotent
delete_item Delete a deadline and its milestones write destructive
list_milestones Study-plan steps for a deadline read read-only
create_milestone Add a step write
update_milestone Edit or check off a step write idempotent
delete_milestone Remove a step write destructive
get_grades Categories, scores, weighted grade, letter read read-only
set_grade_categories Replace category weights write destructive (removed categories lose scores)
add_grade_score Record a score write
delete_grade_score Remove a score write destructive
get_practice_stats Accuracy by topic, weak topics, streak read read-only
list_vocab_decks Flashcard decks read read-only
list_vocab_terms Terms in a deck read read-only
create_vocab_deck Create a deck of terms write
delete_vocab_deck Delete a deck write destructive

Every tool sets title, readOnlyHint, destructiveHint, idempotentHint and openWorldHint: false (tools only touch the member's own Aceversity data). Clients use these to decide when to ask the member for confirmation.

Errors come back as tool results with isError: true and text like not_found: Course not found. so the model can recover (e.g. list courses and retry). Unknown tools and malformed JSON-RPC get JSON-RPC errors.

How a client connects

  1. POST https://api.aceversity.com/mcp with no credentials → 401 and WWW-Authenticate: Bearer resource_metadata="https://api.aceversity.com/.well-known/oauth-protected-resource/mcp".
  2. The client reads that document, finds the authorization server (https://api.aceversity.com), fetches its metadata, registers itself at /oauth/register, and opens /oauth/authorize with PKCE.
  3. The member approves; the client exchanges the code and retries with Authorization: Bearer ace_at_….
  4. initialize → notifications/initialized (answered 202) → tools/list → tools/call.

Try it by hand

curl -s https://api.aceversity.com/mcp \
  -H "Authorization: Bearer $ACEVERSITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_agenda","arguments":{"days":7}}}'

MCP Inspector

npx @modelcontextprotocol/inspector

Choose Streamable HTTP, URL https://api.aceversity.com/mcp. Either use Open Auth Settings → Quick OAuth Flow to test the OAuth path, or add a header Authorization: Bearer ace_sk_…. Then Connect → List Tools and run a few. See Testing for the full checklist.