Reference

API reference

Every tool, resource, prompt, and AI workflow exposed by the CourseFoundry endpoint at POST https://www.coursefoundry.com/api/mcp.

Tools

Call a tool with the tools/call method. There are 22 tools across four groups.

Read tools - available on all key scopes

Tool	Description
`list_courses`	List all courses owned by the authenticated user.
`read_course`	Get course metadata, file list, and AI context for a course.
`get_lesson`	Read the content of a specific lesson file.
`get_ai_context`	Get the AI context (Smithy config) for a course.
`list_files`	List every file in a course with a sha256 hash, byte size, and encoding - so a client can diff a local copy without downloading bodies.
`read_file`	Read any file by path - config, references, stylesheets, images, lessons. Text returns encoding `utf8`; images return raw `base64`.
`list_placeholders`	List a course's image placeholders with their AI prompt, designer brief, target pixel size, every file and line that uses them, and a free `suggested_path` to save the finished image at.

Write tools - require Read + Write scope

Tool	Description
`create_course`	Create a new course with a title and optional description.
`update_course`	Update course metadata (title, description, slug).
`create_lesson`	Create a new lesson file at a given path.
`update_lesson`	Update the content of an existing lesson file.
`publish_course`	Publish or unpublish a course.
`set_ai_context`	Set the AI Smithy context for a course.
`write_file`	Create or overwrite any course file by path (upsert). Image types require `base64` content.
`apply_ops`	Apply a batch of proposed course-change ops (as returned by `chat`) to the course.
`update_placeholder`	Save a refined label, description, AI prompt or designer brief for one placeholder. Only the fields you send change.
`resolve_placeholders`	Replace 1-50 placeholders with images already uploaded to the course (via `write_file`), rewriting every reference to a relative path. All or nothing; a refusal lists every failing pair.

Destructive tools - require Read + Write scope and `confirm: true`

Tool	Description
`delete_lesson`	Delete a lesson file. Must pass `"confirm": true`.
`delete_course`	Delete an entire course. Must pass `"confirm": true`.
`delete_file`	Delete any course file by path. Must pass `"confirm": true`.

json

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "delete_lesson",
    "arguments": {
      "course_id": "YOUR_COURSE_ID",
      "path": "module-2/old-draft.qmd",
      "confirm": true
    }
  },
  "id": 1
}

AI tools

Tool	Description
`run_workflow`	Run a named AI workflow and return the generated content. Consumes AI credits.
`chat`	Ask the course copilot a question in context. Returns the reply plus any proposed change ops, which you apply with `apply_ops`. Consumes AI credits.

run_workflow - AI generation

The run_workflow tool runs one of CourseFoundry's AI workflows and returns generated text. Each call consumes AI credits from your plan. Request shape:

json

{
  "name": "run_workflow",
  "arguments": {
    "workflow": "<workflow_name>",
    "context": { ... }
  }
}

Available workflows

Workflow	Purpose	Key `context` fields
`outline`	Structured course outline with modules and lesson titles.	`title`, `description`
`lesson`	Full lesson body in Quarto Markdown.	`courseTitle`, `lessonTitle`, `outline`
`slides`	Convert lesson content into a slide-ready format.	`lessonContent`, `courseTitle`, `lessonTitle`
`assessment`	Quiz questions and assessment items for a lesson.	`lessonContent`, `courseTitle`
`review`	Critique a lesson for clarity, accuracy, and instructional quality.	`lessonContent`, `courseTitle`
`import`	Convert raw unstructured content into a structured QMD lesson.	`rawContent`, `courseTitle`
`suggest_outcomes`	Suggest SMART learning outcomes for a course.	`courseTitle`, `courseDescription`

Example - generate an outline:

json

{
  "workflow": "outline",
  "context": {
    "title": "Intro to Rust",
    "description": "A beginner course covering ownership, traits, and async."
  }
}

Resources

Resources expose structured data for LLM consumption. Use resources/list to discover them and resources/read to fetch one.

URI	Description
`coursefoundry://user/profile`	Authenticated user profile (plan, credits, username).
`coursefoundry://courses`	List of all courses.
`coursefoundry://course/{id}`	Single course detail.
`coursefoundry://course/{id}/lessons`	All lessons in a course.

bash

curl -X POST https://www.coursefoundry.com/api/mcp \
  -H "Authorization: Bearer cfry_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "resources/read",
    "params": { "uri": "coursefoundry://courses" },
    "id": 1
  }'

Prompts

Use prompts/list to discover built-in prompt templates and prompts/get to retrieve one.

Name	Description
`create-course`	Guided prompt for creating a new course from scratch.
`improve-outcomes`	Prompt for refining learning outcomes.
`generate-lesson`	Prompt for generating a new lesson in a course.
`fill-image-placeholders`	Step-by-step prompt for an agent to produce and resolve a course's image placeholders.

Key scopes

Create a Read-scoped key for CI that only queries data, public integrations, monitoring tools, or anywhere write access would be a security risk. Read-only keys block all write, destructive, and AI tools - a 403 with read_only_scope is returned if a write tool is called. For anything that authors content, use a Read + Write key.

API reference

Tools

Read tools - available on all key scopes

Write tools - require Read + Write scope

Destructive tools - require Read + Write scope and confirm: true

AI tools

run_workflow - AI generation

Available workflows

Resources

Prompts

Key scopes

Destructive tools - require Read + Write scope and `confirm: true`