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, and cohort analytics.

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. Tag goals with custom metadata to track and analyze entire cohorts.

Quick Start

npx @unfoldit/mcp-server

Or install globally:

npm install -g @unfoldit/mcp-server

Configuration

Set the following environment variables:

| Variable | Required | Description | |----------|----------|-------------| | UNFOLD_API_KEY | Yes | Org-scoped API key. Generate at app.unfoldit.com -> Organization -> API Keys | | UNFOLD_API_URL | No | API base URL. Defaults to https://api.unfoldit.com |

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

Available Tools (8)

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 title
• description -- Goal description. More detail produces a better AI plan
• context -- Rich context for the agent:
  • tech_stack -- e.g. ["Python", "React"]
  • team_size -- e.g. 3
  • timeline -- 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 review
• clarification_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" }

Returns: goalId, claimLink, claimToken, progressLink, planGenerationStatus, questions (if auto_respond=false), agentAnswersUsed

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, 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 date
• date_to -- ISO date (YYYY-MM-DD). Only include goals created on or before this date

Returns:

• totalGoals, activeGoals, completedGoals, blockedGoals, completionRate, avgDaysToComplete
• claimsTotal, claimsClaimed, claimsPending, claimsExpired, avgHoursToClaim
• atRiskCount, 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_goal
• answers -- 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 title
• description -- Goal description
• steps (required) -- Array of steps, each with:
  • title (required) -- Step title
  • description -- Step description
  • substeps -- Optional array of substeps with title, description, type (research/work/decision/verification)
• enrich -- Run AI enrichment (default: true). Set false for 0 credits
• enrich_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_goals

List all goals in your org with optional filters. Use metadata to filter to a cohort, 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)
• 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 email
• inactive_days -- Return only goals with no step activity in the last N days (1-365)
• limit -- Max results (default: 50)
• offset -- Pagination offset

Returns: Array of goal statuses with progress, metadata, claimCreatedAt, claimedAt

revoke_claim

Invalidate a claim link so it can no longer be used.

Input:

• claim_token (required) -- The token from the claim link URL

How It Works

Tier 1 -- Semi-Auto (Review agent suggestions)

1. Call create_goal with auto_respond=false and your context
2. Get back questions with agent-suggested answers and confidence levels
3. Review suggestions, override any you disagree with
4. Call submit_clarification to trigger plan generation
5. Poll get_goal_status until planGenerationStatus is "completed"

Tier 2 -- Full-Auto (Agent handles everything)

1. Call create_goal with context (auto_respond defaults to true)
2. Agent answers all clarification questions using your context + user history
3. Plan generates in the background (15-30s)
4. Get a claim link immediately -- send it to your user
5. Poll get_goal_status for completion and agentAnswersUsed transparency

Tier 3 -- Import (Bring your own steps)

1. Call import_plan with your steps and substeps
2. AI enriches with dependencies, durations, severity, critical path
3. Plan is ready immediately (no clarification needed)
4. Get a claim link and enriched step metadata

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

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

Getting an API Key

1. Go to app.unfoldit.com
2. Create or switch to your organization
3. Go to Organization settings
4. Scroll to API Keys section
5. Click + Create Key, give it a name, and copy the key

Learn More

• Unfold It -- AI-powered goal planning and execution platform
• Developers -- API and MCP documentation
• GitHub -- Source code and issues

License

MIT