MCP server
Cursiva ships an MCP server (Model Context Protocol) so AI clients — claude.ai, Claude Desktop, Claude Code, Cursor, and any MCP-compatible agent — can operate your organization in natural language: browse and edit contents, enroll learners, issue refunds, summarize insights. This page covers connecting a client, how authentication and permissions work, what the tools cover, and how to author course content with an AI assistant.
What it is
The server lives at https://mcp.cursiva.io and exposes 68 tools, generated one-per-operation from the same zod contracts that drive the REST API and its OpenAPI document. Each tool is the snake_case form of the API operation — list_contents, enroll_learner, refund_purchase — with the exact same request and response schemas. Anything the API can do, a connected assistant can do by being asked in plain language: the client picks the tool, fills the arguments, and shows you the result.
Because the tools and the REST API share one contract source, they never drift: a field added to the API appears in the matching tool on the same deploy.
Connect
claude.ai and Claude Desktop
- Open Settings → Connectors → Add custom connector.
- Paste
https://mcp.cursiva.ioand confirm. - A browser window opens — sign in with Cursiva (your existing session is reused if you have one).
- Review the consent screen and click Allow.
The connector is now available in your chats, acting as you, with your roles.
Claude Code
With OAuth (a browser login, same consent flow as above):
claude mcp add --transport http cursiva https://mcp.cursiva.io
Or headless, with an organization API key from Settings → Developer → API keys:
claude mcp add --transport http cursiva https://mcp.cursiva.io --header "Authorization: Bearer cs_live_..."
Other MCP clients
Any client that speaks MCP over Streamable HTTP works the same way: point it at https://mcp.cursiva.io. If the client supports OAuth, an unauthenticated request triggers the browser sign-in automatically; otherwise, configure a bearer header with a cs_live_ API key. In Cursor, for example, add the server URL to your MCP configuration and optionally set the Authorization header.
A quick sanity check
Whichever client you connected, ask it something read-only first — list my courses or how many learners enrolled this week? — and confirm the answer matches your dashboard. A working read means the credential, the organization, and the tool wiring are all correct before you let the assistant write anything.
Authentication and permissions
The server accepts two kinds of credentials, and which one you use decides what the assistant is allowed to do:
| OAuth user token | Organization API key | |
|---|---|---|
| Identity | The signed-in user who clicked Allow | The organization itself |
| Permissions | The user's real team roles apply — editor, finance, community | Org-admin authority over the whole organization |
| How you get it | Browser sign-in + consent screen, handled by the client | Created at Settings → Developer → API keys (cs_live_…) |
| Revocation | Revoke the OAuth grant from your account | Revoke the key in the Developer settings |
| Best for | Personal assistants — claude.ai, Desktop, day-to-day Claude Code | Headless agents, CI, shared automation |
A finance-role member connected via OAuth can read sales but cannot rewrite a course; an API key can do both. Pick the narrower credential when the narrower one is enough.
What the tools cover
One tool per API operation, grouped by resource:
| Group | Example tools |
|---|---|
| Organization | get_organization, update_organization, list_members, custom-domain get/set/delete/verify, get_organization_integrations |
| Contents | list_contents, create_content, get_content, update_content, delete_content, publish_content, duplicate_content |
| Authoring | get_document_schema, get_content_document, replace_content_document — the document format reference plus full draft read and replace |
| Learners | list_learners, list_content_learners, enroll_learner, unenroll_learner, reset_learner_progress, enrollment-request list/approve/reject |
| Communities | list_content_communities, create_community, update/delete, add/remove member, set_community_member_role |
| Intake forms | list/create/get/update/delete |
| Tags | list/create/update/delete |
| Coupons | list_content_coupons, create/update/delete |
| Teams | list/create/get/update/delete, add/remove member |
| Sales | list_sales, list_purchases, get_purchase, refund_purchase |
| Insights | get_insights, get_insights_series, get_content_insights, get_content_sales, list_content_reviews |
| Webhooks | list/create/update/delete, list_webhook_deliveries, test_webhook |
The same deliberate gaps as the REST API apply: no personal authentication, no acting as a learner, no API-key minting.
Authoring with AI
The most powerful pair of tools is get_content_document and replace_content_document: together they let an assistant read and rewrite an entire course draft. The loop is always learn the format, read, modify, write:
get_document_schemareturns the full authoring reference: every node type with its exact attrs and a real example, the rigid header rules, and a minimal valid document to start from. Call it once per session before touching any document.get_content_documentreturns the draft as ProseMirror JSON — the same document the composer edits, with sections, quizzes, flashcards, and every other block as typed nodes. See the block reference for the node types and what they render as.- The assistant edits the JSON — adds a section, rewrites a lesson, drafts new quiz questions — and keeps the rest of the document intact.
replace_content_documentwrites the modified draft back, replacing it whole.publish_contentmakes it live. Until then, learners see nothing: replacing the draft is always safe to iterate on.
This makes prompts like rewrite the intro section to be friendlier or add a five-question quiz after the second section work end to end — the assistant fetches the document, performs the surgery, and writes it back.
For risk-free experiments, duplicate_content first: the copy gets its own draft with no learners attached, so an assistant can restructure it aggressively while the original stays untouched.
Example prompts
Once connected, these are the kinds of requests that resolve to one or two tool calls:
- Create a 20% coupon called LAUNCH20 for the Zero to Production course, limited to 50 uses.
- Enroll ana@example.com in the Onboarding course and put her in the March cohort.
- Summarize this month's sales against last month and flag any refunds.
- Draft a new section on error handling after the API basics section, matching the course tone.
- Who signed up this week but has not started anything yet?
- Approve all pending enrollment requests that answered yes to the prerequisite question.
Limits and errors
- Rate limits are shared with the REST API: 240 reads/min and 60 writes/min per credential. When a call is throttled, the API's rate-limit message comes back inside the tool result.
- Failed calls are not protocol errors — they return as tool results flagged
isError, carrying the HTTP status and the API's error message, so the assistant can read the reason and adjust. - Stateless — the server keeps no session between calls. Every call authenticates independently, and there is nothing to resume or clean up.
Protocol notes
For client authors: the transport is Streamable HTTP with plain JSON responses — the server supports initialize, tools/list, and tools/call, and does not open an SSE stream. Unauthenticated requests get a 401 with a WWW-Authenticate challenge, which triggers OAuth discovery and dynamic client registration automatically in compliant clients — that is the whole magic behind the browser sign-in.