Unfold It MCP Server
OfficialClick on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Unfold It MCP Server Create a goal to learn Python in 3 months"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Unfold It MCP Server
Connect AI assistants to Unfold It -- create goals with AI-generated plans, agent-assisted clarification, plan import with enrichment, individual progress tracking, cohort analytics, and skill assessments.
Built for platforms (academies, LMS tools, coaching apps) that want to use Unfold It as their execution layer. Three autonomy tiers: fully autonomous, semi-auto with review, or import your own steps with AI enrichment. Generate skill assessments with AI-validated MCQs, score them, and automatically create targeted learning paths from the results. Tag goals with custom metadata to track and analyze entire cohorts.
Quick Start
npx @unfoldit/mcp-serverOr install globally:
npm install -g @unfoldit/mcp-serverRelated MCP server: mochi-quest
Configuration
Set the following environment variables:
Variable | Required | Description |
| Yes | Org-scoped API key. Generate at app.unfoldit.com -> Organization -> API Keys |
| No | API base URL. Defaults to |
Claude Desktop / Claude Code
Add to your MCP config (claude_desktop_config.json or .mcp.json):
{
"mcpServers": {
"unfoldit": {
"command": "npx",
"args": ["@unfoldit/mcp-server"],
"env": {
"UNFOLD_API_KEY": "unfold_sk_..."
}
}
}
}Cursor
Add to .cursor/mcp.json in your project:
{
"mcpServers": {
"unfoldit": {
"command": "npx",
"args": ["@unfoldit/mcp-server"],
"env": {
"UNFOLD_API_KEY": "unfold_sk_..."
}
}
}
}API Key Scopes
Your API key needs specific scopes depending on which tools you use:
Scope | Tools | Included by default? |
| create_goal, unfold_goal, submit_clarification, import_plan, delete_goal | Yes |
| get_goal_status, list_goals, get_analytics, get_clarification | Yes |
| revoke_claim | Yes |
| generate_skill_assessment | No -- must be granted explicitly |
| score_skill_assessment | No -- must be granted explicitly |
| get_assessment_capabilities | No -- must be granted explicitly |
Assessment scopes are opt-in. Ask your org owner to enable them in the API Key settings.
Available Tools (13)
create_goal
Create a goal with an AI-generated plan. The agent auto-answers clarification questions using the context you provide. Set auto_respond=false to review agent suggestions before the plan generates. Tag goals with metadata to group and analyse entire cohorts.
Input:
title(required) -- Goal titledescription-- Goal description. More detail produces a better AI plancontext-- Rich context for the agent:tech_stack-- e.g. ["Python", "React"]team_size-- e.g. 3timeline-- e.g. "3 months", "Q3 2026"constraints-- e.g. "2 hours per week"experience_level-- e.g. "beginner", "advanced"industry-- e.g. "fintech"additional_notes-- Any other context
auto_respond-- true (default): agent answers all questions. false: returns questions with suggestions for reviewclarification_answers-- Pre-set answers by question ID (agent skips these)goal_context-- "personal" or "professional" (default: "professional")priority-- "low", "medium", or "high" (default: "medium")claim_expires_in_days-- Claim link validity (default: 30)progress_share-- Generate embeddable progress link (default: true)metadata-- Custom key-value tags for analytics grouping, e.g.{ cohort: "spring-2026", track: "frontend" }category-- Resource category hint: "learning", "health_adhd", or "general". Auto-detected from goal title and description if not provided. Determines which sources and search strategies are used when attaching resources to substeps.resource_world-- Override resource discovery for this goal:preferred_sources-- Source domains to prioritise, e.g.["coursera.org", "docs.python.org"]excluded_sources-- Source domains to suppressyoutube_playlists-- YouTube playlist IDs to draw resources fromlms_search_endpoint-- Custom LMS search endpoint URLcontent_policies--{ require_verified_sources, show_disclaimer, disclaimer_text }
assessment(since v0.7.0) -- Structured assessment input the planner uses to bias step selection. Discriminated byassessment_type:skill_proficiencyv1 -- Drop thescore_skill_assessmentresponse straight in. The planner prioritises weak facets, compresses strong ones, and anchors steps inwork_item_context.clinical_intakev1 -- ADHD / coaching / clinical context. Wire shape is locked; the prompt builder is currently stubbed and returnsassessment_type_not_supporteduntil a real partner drives it. Sensitive type -- requires superadmin enablement per org.generalv1 -- Catch-all for assessment data that does not fit either typed shape. Treated as soft hints; onlyconstraintshonoured as hard limits.
See GUIDE_ASSESSMENT_TO_PLAN_MCP for the canonical end-to-end walkthrough.
request_id(since v0.8.0, optional, idempotency key) -- Within a 5-minute window, twocreate_goalcalls with the samerequest_idreturn the SAME goal and claim link instead of creating a new one. See Idempotency below for the rules. Omit to get a fresh goal on every call (default).
Returns: goalId, claimLink, claimToken, progressLink, planGenerationStatus, questions (if auto_respond=false), agentAnswersUsed, idempotentReplay (since v0.8.0), claimStatus (since v0.8.0), warnings (always present, empty when none)
get_goal_status
Get the current status and full step-by-step detail of a goal. Returns individual step data (timestamps, time spent, blocker count, substep progress) when the plan is ready.
Input:
goal_id(required) -- The goal ID from create_goal
Returns: Goal status, progress, resourceCategory, steps[] (with per-step detail when plan is ready), metadata, claimCreatedAt, claimedAt, assignedTo, agentAnswersUsed
get_analytics
Aggregated cohort analytics across all API-created goals. Returns KPIs, at-risk learners, a step-level drop-off funnel, and optional breakdowns by metadata dimension or resource type.
Input:
group_by-- Metadata key to break down completion rates by (e.g. "track", "cohort", "department")inactive_days-- Flag goals with no step activity in this many days as at-risk (default: 7)include_funnel-- Include step-by-step completion funnel (default: true)include_resources-- Include resource engagement by type and source (default: false)metadata-- Filter to a specific cohort or segment, e.g.{ cohort: "spring-2026" }date_from-- ISO date (YYYY-MM-DD). Only include goals created on or after this datedate_to-- ISO date (YYYY-MM-DD). Only include goals created on or before this date
Returns:
totalGoals,activeGoals,completedGoals,blockedGoals,completionRate,avgDaysToCompleteclaimsTotal,claimsClaimed,claimsPending,claimsExpired,avgHoursToClaimatRiskCount,atRiskGoals[](goalId, title, metadata, daysInactive, progressPercent)completionByDimension[](when group_by is set)stepFunnel[](stepOrder, stepTitle, completionRate, avgHoursToComplete)resourceEngagement[](when include_resources=true)
get_clarification
Get pending clarification questions with agent-suggested answers and confidence levels. Use after create_goal with auto_respond=false.
Input:
goal_id(required) -- The goal ID from create_goal
Returns: Questions with agentAnswer, agentConfidence (high/medium/low/fallback), agentSource
submit_clarification
Submit answers to clarification questions and trigger plan generation. Provide your own answers for questions you want to override. Agent suggestions are kept for the rest.
Input:
goal_id(required) -- The goal ID from create_goalanswers-- Your answers keyed by question ID (only include overrides)accept_agent_answers-- Accept agent suggestions for unoverridden questions (default: true)
Returns: goalId, status, planGenerationStatus, agentAnswersUsed
import_plan
Import a pre-formulated plan with steps and substeps. Skips clarification entirely. AI enriches steps with dependencies, critical path, duration estimates, severity, complexity, and quick-win flags.
Input:
title(required) -- Goal titledescription-- Goal descriptionsteps(required) -- Array of steps, each with:title(required) -- Step titledescription-- Step descriptionsubsteps-- Optional array of substeps with title, description, type (research/work/decision/verification)
enrich-- Run AI enrichment (default: true). Set false for 0 creditsenrich_options-- Control which enrichment features to run:dependencies,critical_path,duration_estimates,severity,complexity,quick_wins,resources
goal_context-- "personal" or "professional" (default: "professional")priority-- "low", "medium", or "high" (default: "medium")claim_expires_in_days-- Claim link validity (default: 30)progress_share-- Generate embeddable progress link (default: true)metadata-- Custom key-value tags for analytics grouping, e.g.{ cohort: "spring-2026", track: "backend" }
Returns: goalId, planId, enriched steps[] with metadata, claimLink
list_resource_categories
List available resource categories for goal classification. Returns each category's active providers, content safety policies, and disclaimer text. Use this to build adaptive UIs or to discover which categories are available before creating goals.
Input: None
Returns: Array of categories, each with id, name, description, activeProviders, showDisclaimer, disclaimerText
list_goals
List all goals in your org with optional filters. Use metadata to filter to a cohort, category to segment by goal type, assigned_email to look up a specific learner, or inactive_days to find at-risk goals without pulling full analytics.
Input:
status-- Filter by goal status (draft, in_progress, completed, blocked, paused)claim_status-- Filter by claim status (unclaimed, claimed, expired, revoked)category-- Filter by resource category (learning, health_adhd, general). Use this to segment ADHD goals from learning goals in a mixed cohort.metadata-- Filter by metadata tag(s) in "key=value" format, e.g.["track=frontend", "cohort=spring-2026"]assigned_email-- Return only the goal assigned to this learner emailinactive_days-- Return only goals with no step activity in the last N days (1-365)include_steps(since v0.9.1) -- Include per-step details (steps[]) for each goal whose plan is ready. Off by default to keep list payloads lean; set true to render step lists without aget_goal_statuscall per goal.limit-- Max results (default: 50, max: 100)offset-- Pagination offset
Returns: Array of goal statuses with progress, resourceCategory, metadata, claimCreatedAt, claimedAt. When include_steps=true, each goal whose plan is ready also carries steps[] -- the same per-step shape as get_goal_status (timestamps, time spent, blocker count, substep counts). Goals still generating return steps: null. Steps are not paginated; the full step list is returned per goal.
revoke_claim
Invalidate a claim link so it can no longer be used.
Input:
claim_token(required) -- The token from the claim link URL
delete_goal
Delete a goal created via the API. Main use case: after a learner retakes a skill assessment, call create_goal with the new suggested_goal_seed and then delete_goal on the obsolete goal so the dashboard shows the current goal instead of duplicates. Soft delete by default (recoverable); set hard_delete=true to remove the row permanently. Scoped to api-created goals -- cannot delete goals a user created in the webapp UI.
Input:
goal_id(required) -- UUID of the goal (thegoalIdreturned by create_goal)hard_delete-- If true, permanently delete the row instead of soft-deleting. Default false.
generate_skill_assessment
Generate a skill-proficiency assessment (MCQs) for a learner. Questions are AI-generated and validated (structural + semantic checks) before being returned. Returns a signed assessment_token that the learner's answers are scored against.
Input:
work_item_context(required) -- The work item the learner is preparing for:title(required) -- Work item titledescription-- Work item description (max 2000 chars)domain_tags-- Tags for question anchoring
skill(required) -- Skill to assess (e.g. "Python", "SQL", "Project Management")target_proficiency(required) -- Band the learner should reach: "beginner", "low", "medium", "high"num_questions(required) -- Number of MCQs to generate (3-20)difficulty_mix-- Distribution as{easy, medium, hard}floats summing to 1.0. Default:{easy: 0.2, medium: 0.5, hard: 0.3}band_thresholds-- Custom proficiency band ranges. Default: beginner [0,10], low [11,50], medium [51,85], high [86,100]language-- ISO language code (default: "en")request_id(required) -- Idempotency key. Same request_id returns the same assessment.
Returns: assessment_token, questions[] (stem, options, difficulty, skill_facet), band_map, max_raw_score, target_band, model_meta
Requires scope: assessment:generate
score_skill_assessment
Score a submitted assessment using the signed assessment_token from generate_skill_assessment. Returns the learner's proficiency band, gap vs target, and per-question results. When the learner falls short, includes a suggested_goal_seed you can pass to create_goal to create a targeted learning path.
Input:
assessment_token(required) -- The signed token from generate_skill_assessmentanswers(required) -- Array of{question_id, selected_option_id}(at least one)band_thresholds-- Optional override of proficiency band ranges (defaults to the thresholds embedded in the token)request_id(required) -- Idempotency key
Returns: raw_score, max_raw_score, raw_pct, band, target_band, gap_bands, per_question[], per_facet[] (server-side aggregation per sub-skill with total, correct, raw_pct, classification: weak | strong | mixed), weak_facets[], strong_facets[], facet_coverage (full | partial | difficulty_fallback), recommended_action (none / create_unfold_goal), suggested_goal_seed
Chaining tip: This response is shape-compatible with
create_goal's newassessmentfield (skill_proficiency v1). Drop it in with three header fields added (assessment_type: "skill_proficiency",schema_version: "v1",assessed_at: <ISO timestamp>) and the planner uses it directly. No client-side join logic, no threshold tuning.
Requires scope: assessment:score
get_assessment_capabilities
Get supported parameters for skill assessments. Use this to introspect before calling generate_skill_assessment. No input parameters required.
Returns: schema_version, supported_languages, min_questions, max_questions, supported_proficiency_bands, default_band_thresholds, default_difficulty_mix, open_domain, token_ttl_seconds
Requires scope: assessment:read_capabilities
Idempotency
Available since v0.8.0.
create_goal accepts an optional request_id so a partner can retry safely without producing duplicate goals.
The rules
Scope the key to one logical operation. A "logical operation" is one learner / one enrollment. Construct the key from your own per-learner identifier, for example:
request_id = "enrollment:42:learner:7" request_id = "course:python-101:user:abc-123"Reuse the key on retries, not on new learners. If a network blip or process restart makes you re-send the same call for the same learner, use the same
request_id. If you are creating a goal for a DIFFERENT learner, generate a NEW key.Do NOT derive the key from the body. Two learners enrolled in the same course will produce identical title / description / assessment payloads. If you reuse a body-derived key, the second learner will receive a claim link the first learner already claimed.
Without a
request_id, every call creates a fresh goal. This is the default and is always safe.
Cache window
Two calls with the same tenant + request_id within 5 minutes return the same response. After 5 minutes the key falls out of cache and a fresh call creates a new goal. Best-effort across pod restarts and horizontal scaling today; treat the window as a retry helper, not a deduplication guarantee.
Detecting a replay
Two new fields on the response tell you what happened:
idempotentReplay: true-- this response was served from cache. A prior call with the samerequest_idproduced this goal.claimStatus: "unclaimed" | "claimed" | "expired" | "revoked"-- current state of the underlying claim token, refreshed from the DB on every replay.nullon a fresh create (implicitly "unclaimed").
Branch on this when handling retries:
const result = await create_goal({ title, request_id: enrollmentKey });
if (result.idempotentReplay && result.claimStatus && result.claimStatus !== "unclaimed") {
// The link was already consumed by the original recipient. Don't
// forward it again -- prompt the human or open a support ticket
// depending on your flow.
} else {
// Safe to forward the claimLink to the learner.
}How It Works
Tier 1 -- Semi-Auto (Review agent suggestions)
Call
create_goalwithauto_respond=falseand your contextGet back questions with agent-suggested answers and confidence levels
Review suggestions, override any you disagree with
Call
submit_clarificationto trigger plan generationPoll
get_goal_statusuntilplanGenerationStatusis "completed"
Tier 2 -- Full-Auto (Agent handles everything)
Call
create_goalwith context (auto_respond defaults to true)Agent answers all clarification questions using your context + user history
Plan generates in the background (15-30s)
Get a claim link immediately -- send it to your user
Poll
get_goal_statusfor completion andagentAnswersUsedtransparency
Tier 3 -- Import (Bring your own steps)
Call
import_planwith your steps and substepsAI enriches with dependencies, durations, severity, critical path
Plan is ready immediately (no clarification needed)
Get a claim link and enriched step metadata
Assess-then-Learn (Assessment to goal) [updated v0.7.0]
The canonical chain that turns a scored assessment into a personalised plan, with no client-side join logic:
Call
generate_skill_assessmentwith the skill, target proficiency, and work item contextPresent questions to the learner in your UI
Call
score_skill_assessmentwith the token and the learner's answers. Response includesper_facet,weak_facets,strong_facets,facet_coverage(server-side aggregation).Call
create_goalwith the score response dropped into the newassessmentfield (skill_proficiency v1). The planner uses weak/strong facets to bias steps and anchors them inwork_item_context.Send the claim link to the learner.
Full walkthrough with payload examples for skill_proficiency, general, and clinical_intake lives at GUIDE_ASSESSMENT_TO_PLAN_MCP.
Legacy path. Pre-v0.7.0 integrations stuffed the score into
additional_context.unfold_assessmentper the payload convention. That still works onPOST /api/v1/ext/goalsfor backwards compat; behind the scenes both paths now route through the same prompt-builder registry. New integrations should use the structuredassessmentfield oncreate_goal.
Example Prompts
"Create a Python certification learning path for a beginner with 2 hours per week for 3 months."
"Import our Jira sprint backlog as a goal with dependencies and time estimates."
"Create a coaching plan for Sarah but let me review the questions before generating the plan."
"Create an ADHD morning routine coaching plan with category health_adhd for a patient who struggles with time blindness."
"List all health_adhd goals in the spring cohort and show me which ones are at risk."
"Show me all goals where the claim link hasn't been used yet."
"What's the progress on goal abc-123? Has the learner started?"
"Generate a Python assessment with 8 questions for someone who needs medium proficiency to work on the ML pipeline."
"Score this assessment and create a goal from the results if the learner didn't reach the target."
Getting an API Key
Go to app.unfoldit.com
Create or switch to your organization
Go to Organization settings
Scroll to API Keys section
Click + Create Key, give it a name, and copy the key
Typed errors and warnings (v0.7.0+)
When a tool fails with a typed error, the response is a structured JSON envelope rather than a stringified message. Branch on error_code:
| When | Notes |
| BYO provider role is not configured | Response includes |
| BYO provider key rejected | Includes |
| BYO provider returned quota/billing error | Includes |
| BYO provider 5xx or circuit breaker open | Transient; retry later |
|
| Response includes |
| Tenant has not opted into this assessment type | Sensitive types (clinical_intake) need superadmin enablement |
| Assessment token tampered or past TTL | Regenerate via generate_skill_assessment |
| Same request_id used with different request body | Pick a new request_id |
| Generation output failed validation after retry budget | Retry with different request_id |
Successful responses on goal creation also carry warnings: ApiWarning[] (always present, empty when none). Known warning codes:
| When |
|
|
| Both structured |
Both branches preserve the structured envelope so AI coding agents can deterministically branch on the error_code or warning code strings. See the versioning policy for stability guarantees on these codes.
Versioning
This package follows semver. Pin a minor version range ("@unfoldit/mcp-server": "^0.8.0") -- you will get fixes and additive features automatically; breaking changes require a major version bump. We support the latest two minor versions; older minors receive security fixes only.
Note: in the pre-1.0 era, each minor bump (e.g. 0.7.x -> 0.8.0) may include additive surface changes such as new optional request fields or new response fields. Existing code keeps working; opt in to new behaviour as you need it.
See GUIDE_MCP_VERSIONING for the full policy. See CHANGELOG.md for what changed in each release.
Learn More
Unfold It -- AI-powered goal planning and execution platform
Developers -- API and MCP documentation
GitHub -- Source code and issues
Assessment-to-Plan guide -- End-to-end walkthrough for the score-to-goal chain
Versioning policy -- Semver discipline, supported-versions window, deprecation policy
License
MIT
Available Tools
13 toolscreate_goalA
Create a goal in your Unfold org with an AI-generated plan.
Returns a one-time claim link to send to the user. When they click it, they auto-join your org, get assigned the goal, and land directly on it with a fully AI-generated plan ready to execute.
The plan generates asynchronously (15-30s). The claim link works immediately. Use get_goal_status to check when planGenerationStatus changes to "completed".
With auto_respond=true (default), the agent answers all clarification questions automatically using the provided context. Set auto_respond=false to get questions back with agent suggestions for client review -- then use submit_clarification to provide your answers.
CHAINING:
If you have an assessment scored via score_skill_assessment, drop its response (band, target_band, per_facet, weak_facets, work_item_context) into the 'assessment' field. The planner will prioritise weak facets, skip strong ones, and anchor steps in the work item.
Each goal is for one user. Call this once per learner/user.
TYPED ERRORS (branch on error_code):
"models_not_configured": tenant's BYO provider has no role configured. Response includes settings_url for the user to fix it.
"provider_unauthorized" / "provider_quota_exceeded": BYO provider key rejected. Response may include switch_to_unfold_ai CTA.
"assessment_type_not_supported": you sent an assessment whose prompt builder is not yet wired (e.g. clinical_intake before partner integration). Response.details.supported lists what IS wired.
WARNINGS (non-fatal, surfaced in response.warnings):
"category_assessment_type_mismatch": category and assessment_type disagree (e.g. learning + clinical_intake). The plan was generated using assessment_type. Set category to align if you want category-aware resource routing.
"duplicate_assessment_input": you sent both the structured 'assessment' field and the legacy unfold_assessment envelope inside additional_context. Structured wins.
Inputs: title (required), context, category, metadata, +10 more.
delete_goalA
Delete a goal created via the API.
Use this when regenerating a goal after a learner retakes a skill assessment: call create_goal with the new suggested_goal_seed, then call delete_goal on the obsolete goal so the learner's dashboard shows the current goal instead of duplicates.
Soft delete by default (status='deleted'); the dashboard already filters these out, but a superadmin can restore them. Set hard_delete=true to permanently remove the row and cascade to steps, plans, and share links.
Scoped to api-created goals in your org -- you cannot delete goals a user created in the webapp UI. Calling twice with the same goal_id is safe (soft delete is idempotent).
Inputs: goal_id (required), hard_delete.
generate_skill_assessmentA
Generate a skill-proficiency assessment (MCQs) for a learner.
You provide a skill, target proficiency, number of questions, and the work item the learner is preparing for. Unfold returns the questions with multiple-choice options, a signed assessment_token, and a proficiency band map. The learner answers in your UI; then call score_skill_assessment with the token and answers.
Questions are AI-generated and validated (structural + semantic) before being returned. The assessment_token is HMAC-signed and tamper-proof; it contains the answer key AND per-question facet labels (since v0.7.0) so scoring is stateless and deterministic, and score returns per-facet aggregation without you doing any client-side joins.
CHAINING:
work_item_context is the strongest grounding signal: questions get anchored to it instead of being generic textbook items. Pass title + description whenever you have them.
The same work_item_context flows through to score_skill_assessment's suggested_goal_seed, then into create_goal. Keep it consistent across the chain.
TYPED ERRORS (branch on error_code):
"models_not_configured" / "provider_unauthorized" / "provider_quota_exceeded" / "provider_unavailable" / "provider_request_invalid": LLM provider issues. Some include settings_url and switch_to_unfold_ai CTA.
"validation_failed": generation produced output the validator rejected after retry budget. Retry with a different request_id, or reduce num_questions.
"idempotency_conflict": same request_id was used with a different request body; pick a new request_id.
Requires the "assessment:generate" scope on your org API key.
Inputs: skill (required), request_id (required), num_questions (required), work_item_context (required), +4 more.
get_analyticsA
Get aggregated analytics for your organization's goals.
Returns cohort KPIs (total, active, completed, blocked), claim metrics (activation rate, time-to-claim), at-risk learners (inactive for N days), an optional step-level completion funnel, and optional resource engagement breakdown.
Use groupBy to break down completion rates by a metadata dimension (e.g. groupBy="track" shows completion rates for frontend, backend, etc).
Use the metadata filter to narrow the scope to a specific cohort or department (e.g. metadata={cohort: "spring-2026"}).
Examples:
"How is the spring 2026 cohort doing?" -> get_analytics({ metadata: { cohort: "spring-2026" } })
"Which track has the highest completion rate?" -> get_analytics({ groupBy: "track" })
"How many students are at risk this week?" -> get_analytics({ inactiveDays: 7 })
"Show me the step-by-step funnel for the frontend track" -> get_analytics({ metadata: { track: "frontend" }, includeFunnel: true })
Inputs: date_to, group_by, metadata, date_from, +3 more.
get_assessment_capabilitiesA
Get supported parameters for skill assessments.
Returns the schema version, supported languages, min/max question count, proficiency bands, default band thresholds, default difficulty mix, and whether the system is open-domain (accepts any skill) or restricted.
Use this to introspect before calling generate_skill_assessment. No parameters required.
Requires the "assessment:read_capabilities" scope on your org API key.
Inputs: no named parameters.
get_clarificationA
Get pending clarification questions for a goal with agent-suggested answers.
Use this after create_goal with auto_respond=false. Returns the list of clarification questions along with what the agent suggested for each one, including confidence levels and reasoning.
Review the suggestions, then use submit_clarification to accept or override them.
Inputs: goal_id (required).
get_goal_statusA
Get the current status and progress of a goal.
Returns who claimed it, step completion breakdown, plan generation status, and the embeddable progress report link.
Use this to check if plan generation is complete (planGenerationStatus: "completed") or to monitor a learner's progress.
Inputs: goal_id (required).
import_planA
Import a pre-formulated plan with steps and substeps into Unfold.
Skips clarification entirely. Use this when you already have a structured plan (e.g. from Jira, Linear, or your own planning tool).
Optionally enriches steps with AI-generated metadata: dependencies between steps, critical path identification, duration estimates, severity/complexity ratings, and quick-win flags. Set enrich=false to skip AI enrichment (0 credits).
Returns the goal with a claim link and the enriched step list.
Inputs: steps (required), title (required), enrich, priority, +5 more.
list_goalsA
List all goals in your org created via the API.
Filter by goal status (draft, in_progress, completed), claim status (unclaimed, claimed, expired, revoked), metadata tags, assigned learner email, or inactivity (at-risk detection).
Use this to see all learner goals, check progress across a cohort, find unused claim links, or identify learners who have gone inactive.
For aggregate cohort metrics, use get_analytics instead.
Inputs: limit, offset, status, category, +5 more.
list_resource_categoriesA
List available resource categories for goal classification.
Returns the categories you can use in create_goal's category field or
as a filter in list_goals. Each category has different resource providers,
content safety policies, and plan generation behavior.
For example, "health_adhd" restricts resources to curated clinical sources, excludes medication content, adds disclaimers, and generates shorter substeps with transition rituals. "learning" adds YouTube, GitHub, and Official Docs providers alongside web search.
Use this to build adaptive UIs that show category-specific options to your users.
Inputs: no named parameters.
revoke_claimA
Invalidate a claim link so it can no longer be used.
Does not remove access from a user who already claimed the goal. Use this if a link was sent to the wrong person or needs to be regenerated.
Inputs: claim_token (required).
score_skill_assessmentA
Score a skill assessment using answers and the assessment_token from generate_skill_assessment.
Returns the raw score, percentage, proficiency band, gap vs target, and per-question results. When the learner falls short of the target band, includes a suggested_goal_seed you can pass to create_goal.
PER-FACET AGGREGATION (since v0.7.0): Response also includes per_facet (one entry per sub-skill with total, correct, raw_pct, classification) and shortlists weak_facets + strong_facets. Aggregation is computed server-side from facets embedded in the signed token, so partners do not write join logic. The facet_coverage field tells you whether facet labels are real ("full"), partially synthetic ("partial"), or entirely difficulty-bucket fallbacks ("difficulty_fallback") -- soften "weak in X" UI framing when coverage is not "full".
CHAINING into create_goal: The shape of this response is purpose-built to drop straight into create_goal's 'assessment' field (as a skill_proficiency v1 variant):
band -> achieved_band
target_band -> target_band
raw_pct, gap_bands -> same names
weak_facets, strong_facets -> same names
work_item_context comes from your original generate_skill_assessment call Add assessment_type: "skill_proficiency", schema_version: "v1", and assessed_at (ISO 8601 current time) headers.
Scoring is stateless and deterministic: the signed assessment_token contains the answer key. Tampered or expired tokens are rejected. Same request_id returns the same result (idempotent).
TYPED ERRORS (branch on error_code):
"token_invalid": signature mismatch or malformed token. Regenerate via generate_skill_assessment.
"assessment_expired": token past TTL. Regenerate.
"idempotency_conflict": same request_id was used with different answers; pick a new request_id.
Requires the "assessment:score" scope on your org API key.
Inputs: answers (required), request_id (required), assessment_token (required), band_thresholds.
submit_clarificationA
Submit answers to clarification questions and trigger plan generation.
Use after create_goal with auto_respond=false. Provide your own answers for questions you want to override. Set accept_agent_answers=true (default) to keep the agent's suggestions for all questions you did not explicitly answer.
After submission, the plan generates asynchronously. Use get_goal_status to check when planGenerationStatus changes to "completed".
Inputs: goal_id (required), answers, accept_agent_answers.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool has a clearly distinct purpose, covering goal CRUD, claim management, clarification, plan import, analytics, and assessment lifecycle. No overlap in functionality, and descriptions make boundaries explicit.
All tools follow a consistent verb_noun pattern in snake_case (e.g., create_goal, list_goals, generate_skill_assessment). No deviations or mixed conventions.
With 13 tools, the set is well-scoped for the domain. It provides comprehensive operations without being bloated or sparse, fitting the typical 3-15 range.
The tool surface covers the full lifecycle: goal creation, status tracking, listing, deletion; claim management; clarification handling; plan import; assessment generation, scoring, and capabilities; analytics; and resource categories. No obvious gaps for the domain.
Maintenance
Related MCP Connectors
Run customer onboarding from your AI tool: build plans, deploy agents, find bottlenecks.
Connect assistants to your workspace knowledge, skills, and work tools.
Connect AI assistants to Stellary projects, boards, documents, and governed agent workflows.
Connect AI agents to your Kairos workspace — manage goals, tasks, docs, whiteboards, and forms.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to manage student profiles, track assessments, calculate topic mastery, identify learning gaps, and recommend focus areas. Integrates with Claude Desktop and Claude Code for interactive learning analytics.1MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to act as personal growth coaches, allowing users to set goals, receive personalized daily tasks, and track progress with dynamic replanning and reward systems.-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to interact with the app via MCP tools and resources, supporting self-improvement through goal-setting and metrics tracking on Cloudflare Workers.5MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to conduct research, plan projects, generate PRDs, user stories and task lists, scaffold full-stack starter kits, map codebases, curate context, and execute multi-step development workflows.42 npmMIT