classroomio/prd/mcp-course-authoring/consumption-spec.md

MCP Consumption Spec

Purpose

Define exactly how an MCP client such as Claude Desktop or another agent runtime should consume the ClassroomIO MCP server.

This spec assumes:

1. the agent performs source extraction externally
2. the MCP server only accepts structured course payloads
3. ClassroomIO API is the system of record

Consumption Model

User prompt/source material
  -> Claude or agent
  -> MCP tool call
  -> ClassroomIO API
  -> ClassroomIO DB

The MCP server is consumed as a tool surface, not as a conversational model.

Agent Responsibilities

The agent must:

1. read source material such as PDFs, notes, prompts, or websites
2. infer a structured course outline
3. construct a normalized payload that matches the draft schema
4. call MCP tools with that payload
5. handle validation errors and revise payloads when needed
6. only publish after explicit user confirmation

The agent must not:

1. write directly to the ClassroomIO database
2. assume ClassroomIO will parse raw PDFs
3. assume drafts are automatically published

Authentication Model

Target model

Use an organization-scoped MCP key generated from the org Automation -> MCP tab.

That key should come from the same shared key infrastructure later reused by the Public API.

The MCP server forwards that credential to ClassroomIO on every request.

Example environment:

CLASSROOMIO_API_URL=https://api.classroomio.example
CLASSROOMIO_API_KEY=cio_mcp_xxxxx

Recommended request header:

Authorization: Bearer cio_mcp_xxxxx

Current bootstrap implementation

Until the shared organization key system lands, the local package uses:

Authorization: Bearer <PRIVATE_SERVER_KEY>
cio-org-id: <organization-id>
x-cio-actor-id: <profile-id>

That is an implementation bridge, not the intended long-term auth model.

MCP Transport

v1

• stdio

This is the best default for Claude Desktop and local agent environments.

Future

• SSE or HTTP transport if remote/shared infrastructure is needed

Tool Surface

create_course_draft

Creates a reviewable draft from a normalized payload.

Input:

{
  "sourceType": "prompt",
  "idempotencyKey": "optional-key",
  "summary": {
    "sourceLabel": "Exponential Functions PDF"
  },
  "sourceArtifacts": [
    {
      "type": "pdf",
      "label": "chapter-1.pdf"
    }
  ],
  "draft": {
    "course": {
      "title": "Exponential Functions",
      "description": "A structured introduction to exponential functions.",
      "type": "SELF_PACED",
      "locale": "en"
    },
    "sections": [
      {
        "externalId": "sec-1",
        "title": "Foundations",
        "order": 0
      }
    ],
    "lessons": [
      {
        "externalId": "lesson-1",
        "sectionExternalId": "sec-1",
        "title": "What Is an Exponential Function?",
        "order": 0
      }
    ],
    "lessonLanguages": [
      {
        "lessonExternalId": "lesson-1",
        "locale": "en",
        "content": "<p>Lesson content here</p>"
      }
    ],
    "warnings": []
  }
}

Output:

{
  "draftId": "uuid",
  "status": "DRAFT",
  "summary": {
    "sectionCount": 1,
    "lessonCount": 1,
    "localeCount": 1,
    "warningCount": 0
  },
  "warnings": []
}

get_course_draft

Fetches the current stored draft.

Input:

{
  "draftId": "uuid"
}

Output:

{
  "id": "uuid",
  "status": "DRAFT",
  "draft": {
    "...": "normalized payload"
  },
  "warnings": []
}

update_course_draft

Updates a stored draft with revised structure or content.

Input:

{
  "draftId": "uuid",
  "draft": {
    "...": "updated normalized payload"
  }
}

Output:

{
  "draftId": "uuid",
  "status": "DRAFT",
  "summary": {
    "sectionCount": 3,
    "lessonCount": 12,
    "localeCount": 1,
    "warningCount": 1
  },
  "warnings": [
    {
      "code": "LOW_CONFIDENCE_BOUNDARY",
      "message": "Section split was inferred.",
      "severity": "warning"
    }
  ]
}

publish_course_draft

Publishes a stored draft into real ClassroomIO entities.

Input:

{
  "draftId": "uuid",
  "title": "Optional override",
  "description": "Optional override",
  "type": "SELF_PACED"
}

Output:

{
  "courseId": "uuid",
  "createdSections": 3,
  "createdLessons": 12,
  "localeCount": 1
}

Expected Agent Workflow

Flow A: Prompt-Based Course Creation

1. User asks Claude to create a course.
2. Claude plans the structure.
3. Claude calls create_course_draft.
4. Claude presents the summary to the user.
5. User requests revisions if needed.
6. Claude calls update_course_draft.
7. User confirms publish.
8. Claude calls publish_course_draft.

Flow B: PDF-Based Course Creation

1. User provides PDF to Claude.
2. Claude extracts and structures the content externally.
3. Claude builds normalized payload.
4. Claude calls create_course_draft.
5. Claude presents draft summary and warnings.
6. Claude revises if needed.
7. Claude publishes only after user confirmation.

Draft Schema Rules

The agent must ensure:

1. section.externalId values are unique
2. lesson.externalId values are unique
3. every lesson.sectionExternalId references an existing section
4. every lessonLanguage.lessonExternalId references an existing lesson
5. all required text fields are non-empty

If these rules are violated, ClassroomIO should reject the request with validation errors.

Error Handling Contract

Validation Errors

The MCP client should expect 400-level errors when:

• the payload shape is invalid
• section or lesson references are broken
• required fields are missing

Expected behavior:

1. surface the error to the agent
2. revise payload
3. retry with corrected structure

Authorization Errors

The MCP client should expect:

• 401 for missing or invalid auth
• 403 for valid auth but insufficient org permission

Publish Errors

If publish fails:

1. do not assume partial success
2. inspect returned error
3. fetch the draft again if needed
4. retry only if the failure is clearly safe to retry

Idempotency Guidance

The MCP client should send an idempotencyKey on draft creation when:

• the same source material may be retried
• the same user prompt may be replayed
• the client cannot guarantee exactly-once execution

Use one stable key per logical draft creation request.

Recommended User Experience in Claude

The agent should present:

1. course title
2. section count
3. lesson count
4. warnings
5. a publish confirmation prompt before calling publish_course_draft

The agent should not auto-publish immediately after draft creation.

Minimal v1 MCP Server Requirements

The MCP server should:

1. expose the draft/publish tools above
2. validate required inputs before forwarding
3. forward auth and org context to ClassroomIO
4. return structured JSON outputs to the client
5. avoid embedding model logic

Future Extensions

Possible future tools:

• list_course_drafts
• delete_course_draft
• clone_course_structure
• add_exercises_to_draft
• preview_publish_diff

These are not required for v1.