MCP Server

The @graspful/mcp package is a Model Context Protocol server that exposes all Graspful operations as tools. Any MCP-compatible agent can scaffold, validate, review, and publish courses. The scaffold and fill tools create drafts and TODO stubs. Your external agent reads the source material and writes the actual teaching content.

Getting your API key

The MCP server requires an API key to import or publish. Set GRASPFUL_API_KEY or sign in with the CLI. Local scaffold, fill, validate, and review tools work without a key. Install the CLI first withbun add -g @graspful/cli. You can get a key through browser registration or the creator dashboard:

Web dashboard

Go to graspful.ai → API Keys and create a new key.

CLI register

Run graspful register --email you@example.com to complete browser auth and mint an API key. The CLI saves the key automatically to ~/.graspful/credentials.json.

Credentials file

The MCP server reads saved credentials from ~/.graspful/credentials.json for each tool call. After CLI login or registration, the next tool call uses the new credentials.

Setup

Configure the MCP server in your agent. The server reads GRASPFUL_API_KEY, GRASPFUL_ORG, and GRASPFUL_API_URL from environment variables.

Claude Code

Run this after replacing the placeholder with your API key. User scope keeps the configuration outside the course repository:

claude mcp add --scope user graspful --env GRASPFUL_API_KEY=gsk_your_key_here -- bunx @graspful/mcp

Cursor

Add to your Cursor MCP configuration (Settings > MCP):

.cursor/mcp.json

{
  "mcpServers": {
    "graspful": {
      "command": "npx",
      "args": ["-y", "@graspful/mcp"],
      "env": {
        "GRASPFUL_API_KEY": "gsk_your_key_here",
        "GRASPFUL_ORG": "your-org-slug"
      }
    }
  }
}

OpenAI Codex

Add the server with the Codex CLI. Replace the API key placeholder:

codex mcp add graspful --env GRASPFUL_API_KEY=gsk_your_key_here -- bunx @graspful/mcp

VS Code (Copilot Agent Mode)

Open MCP: Open User Configuration from the Command Palette and add the server below. Use the input prompt to enter your API key. See the VS Code MCP guide for workspace and remote setup.

mcp.json (user configuration)

{
  "inputs": [
    {
      "id": "graspful-api-key",
      "type": "promptString",
      "description": "Graspful API key",
      "password": true
    }
  ],
  "servers": {
    "graspful": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@graspful/mcp"],
      "env": {
        "GRASPFUL_API_KEY": "${input:graspful-api-key}"
      }
    }
  }
}

The two-YAML workflow

Give source material to your external agent and plan the academy first. The agent then uses these tools with YAML strings. Between filling and review, it must replace the generated stubs with authored lessons, worked examples, and practice problems.

graspful_scaffold_course

Generate the knowledge graph skeleton from a topic

graspful_fill_concept

Add stubs, then author and verify their content (repeat per concept)

graspful_review_course

Run 10 quality checks, fix any failures

graspful_validate

Quick schema validation before import

graspful_import_course

Import a draft, or request publication and confirm published: true

graspful_create_brand

Generate brand YAML for the landing page

graspful_import_brand

Import the brand to create the white-label site

Tools

The tools below cover course and brand authoring. Tools that call the Graspful API require the GRASPFUL_API_KEY environment variable.

graspful_scaffold_course

Generate a course YAML skeleton with sections, concepts, and prerequisite edges. Returns a minimal valid YAML structure with TODO placeholders. The scaffold is an unfinished draft and cannot pass publication review. Edit the graph, prerequisites, and difficulty levels before calling graspful_fill_concept. Author every concept before reviewing for publication.

Inputs

topic*	string	Course topic name (e.g., "Linear Algebra")
estimatedHours	number	Estimated total course hours (default: 10)
sourceDocument	string	Reference to source material

Returns

YAML string with course scaffold

graspful_fill_concept

Add knowledge point (KP) and problem stubs to a specific concept. Returns the full updated YAML. Each KP stub includes instruction text, a worked example, and multiple-choice problems with a difficulty staircase (2, 3, 4, 5). Replace the TODO placeholders with real content. Fails if the concept already has KPs.

Inputs

yaml*	string	The full course YAML string
conceptId*	string	ID of the concept to fill (must have 0 KPs)
kps	number	Number of KP stubs to add (default: 2)
problemsPerKp	number	Number of problem stubs per KP (default: 3)

Returns

Full updated YAML string

graspful_validate

Validate any Graspful YAML (course, brand, or academy) against its Zod schema. Auto-detects the file type from the top-level key. For course YAML, also checks that all prerequisite references point to existing concept IDs and the prerequisite graph is a DAG (no cycles). Run this before import to catch errors early.

Inputs

yaml*

string

The YAML string to validate

Returns

{ valid, fileType, errors[], stats }

graspful_review_course

Run all 10 mechanical quality checks on a course YAML. Returns a score (e.g., "8/10") with details on each failure. The checks: yaml_parses, unique_problem_ids, publication_readiness, question_deduplication, difficulty_staircase, problem_teaching_alignment, problem_variant_depth, instruction_formatting, worked_example_coverage, import_dry_run. A score of 10/10 means the automated checks passed. Review source accuracy, answer keys, and teaching quality before publishing.

Inputs

yaml*

string

The full course YAML string to review

Returns

{ passed, score, failures[], warnings[], stats }

graspful_import_course

Import a course YAML into a Graspful organization. Creates the course as a draft by default. If publish=true, the server runs the review gate first. A failed publication can leave the imported course as a draft and returns failure details. Confirm published: true before reporting success. Requires GRASPFUL_API_KEY.

Inputs

yaml*	string	The full course YAML string
org*	string	Organization slug (e.g., "acme-learning")
publish	boolean	Publish immediately (runs review gate). Default: false

Returns

{ courseId, url, published, reviewFailures? }

graspful_publish_course

Request publication of a draft course. The server runs the review gate. Confirm published: true in the result and report failure details if publication fails. Requires GRASPFUL_API_KEY.

Inputs

courseId*	string	The course ID (UUID) to publish
org*	string	Organization slug

Returns

{ courseId, published }

graspful_describe_course

Compute statistics for a course YAML without importing it. Useful for tracking authoring progress. Returns concept counts (authored vs stubs), KP and problem totals, graph depth, missing content counts, and per-section breakdowns.

Inputs

yaml*

string

The full course YAML string

Returns

{ courseName, courseId, concepts, authoredConcepts, stubConcepts, knowledgePoints, problems, graphDepth, sections[] }

graspful_create_brand

Generate a brand YAML scaffold for a white-label learning site. Niche presets (education, healthcare, finance, tech, legal) set appropriate colors, taglines, and copy. The returned YAML includes brand identity, theme, landing page sections (hero, features, how-it-works, FAQ), and SEO config. Edit and then import with graspful_import_brand.

Inputs

niche*	string	Brand niche: education, healthcare, finance, tech, or legal
name	string	Brand name (default: "{Niche} Academy")
domain	string	Custom domain (default: "{slug}.graspful.ai")
orgSlug	string	Organization slug to associate with

Returns

YAML string with brand scaffold

graspful_import_brand

Import a brand YAML into Graspful. Creates the white-label site configuration including domain, theme, landing page, and SEO. Requires GRASPFUL_API_KEY.

Inputs

yaml*

string

The full brand YAML string

Returns

{ slug, domain, verificationStatus }

graspful_list_courses

List all courses in a Graspful organization. Returns an array of courses with their IDs, names, published status, and stats. Requires GRASPFUL_API_KEY.

Inputs

org*

string

Organization slug (e.g., "acme-learning")

Returns

Array of { courseId, name, published, stats }