MCP Server

The @graspful/mcp package is a Model Context Protocol server that exposes all Graspful operations as tools. Any MCP-compatible agent can create, validate, review, and publish courses.

Setup

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

Claude Code

Add to your claude_desktop_config.json:

claude_desktop_config.json

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

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"
      }
    }
  }
}

OpenAI Codex

Codex supports MCP tool use via its CLI configuration:

codex_config.json

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

VS Code (Copilot Agent Mode)

Add to your VS Code settings for MCP support in agent mode:

.vscode/settings.json

{
  "github.copilot.chat.mcpServers": {
    "graspful": {
      "command": "npx",
      "args": ["-y", "@graspful/mcp"],
      "env": {
        "GRASPFUL_API_KEY": "gsk_your_key_here"
      }
    }
  }
}

The two-YAML workflow

Agents use MCP tools in sequence to build a complete product. The workflow mirrors the CLI quickstart but operates on YAML strings instead of files.

graspful_scaffold_course

Generate the knowledge graph skeleton from a topic

graspful_fill_concept

Add KPs and problems to each concept (repeat per concept)

graspful_review_course

Run 10 quality checks, fix any failures

graspful_validate

Quick schema validation before import

graspful_import_course

Import and optionally publish

graspful_create_brand

Generate brand YAML for the landing page

graspful_import_brand

Import the brand to create the white-label site

Tools

The MCP server exposes 10 tools. 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. This is step 1 of the two-YAML workflow. The scaffold contains NO learning content — just the graph structure. Edit the returned YAML to add more concepts, adjust prerequisites, and set difficulty levels before calling graspful_fill_concept.

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 10 checks: yaml_parses, unique_problem_ids, prerequisites_valid, question_deduplication, difficulty_staircase, cross_concept_coverage, problem_variant_depth, instruction_formatting, worked_example_coverage, import_dry_run. A score of 10/10 is required for 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. If review fails, the course is imported as a draft and failure details are returned. 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

Publish a draft course. The server runs the review gate — the course must pass all 10 quality checks. 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.com")
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 }