Level-Up MCP Server

A Level-up MCP server that tracks XP, levels, skills, and tasks for humans and AI agents. Train your agents, install new skills, enhance their workflows and optimize their output. Get them to level-up their performance!

What It Does

Level-Up tracks productive work performed by you and your AI agents, awarding XP, leveling up skills, and unlocking achievements.

• Users have a Main Level + 3 Class Levels (Trainer, Orchestrator, Partner)
• Agents have Levels, Skills with proficiency (0-10), and Integrity scores
• Tasks earn XP based on type, difficulty, output quality, and completion
• Achievements unlock as you hit milestones (54 achievements across 8 categories)
• Rank system from E (Analyst/Novice) through S (Supreme/Celestial) with star progression

Quick Start

1. Install

No configuration needed — just add Level-Up to your MCP client and go. The server connects to the shared Level-Up database automatically.

2. Connect to Claude Desktop

Add this to your Claude Desktop config file:

Windows (Microsoft Store): %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

Windows (direct install): %APPDATA%\Claude\claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "level-up": {
      "command": "npx",
      "args": ["-y", "level-up-mcp-server"]
    }
  }
}

Restart Claude Desktop after saving.

2b. Auto-Identify (Optional)

After registering, add your user and agent IDs to the config so Level-Up recognizes you automatically in every new chat:

{
  "mcpServers": {
    "level-up": {
      "command": "npx",
      "args": ["-y", "level-up-mcp-server"],
      "env": {
        "LEVELUP_USER_ID": "<your-user-uuid>",
        "LEVELUP_AGENT_ID": "<your-agent-uuid>"
      }
    }
  }
}

To find your IDs, ask Claude: "Who am I on Level-Up?" or "List my agents".

3. Connect to OpenClaw

Add to your ~/.openclaw/openclaw.json under mcpServers:

{
  "mcpServers": {
    "level-up": {
      "command": "npx",
      "args": ["-y", "level-up-mcp-server"]
    }
  }
}

Then restart: openclaw gateway restart

4. Add the System Prompt

Add this to your agent's system prompt or Claude Desktop custom instructions for automatic task tracking:

You have Level-Up gamification tools installed. Use them proactively:

1. IDENTIFY: On first interaction, call levelup_whoami (no parameters needed)
   to auto-identify the user and their agent. If not found, offer to register.

2. TRACK WORK: When the user asks you to do meaningful work (coding, research,
   writing, analysis — anything that produces a deliverable), silently:
   - Call levelup_infer_task_type to categorize the work
   - Call levelup_start_task when you begin
   - Call levelup_complete_task when you deliver the result
   Do NOT track casual questions, greetings, or simple lookups.

3. EVALUATE: After completing a task, call levelup_submit_agent_evaluation
   with an honest self-assessment. Your integrity score depends on consistency.

4. LEVEL UP: After awarding XP, call levelup_check_level_up to apply any
   pending level-ups.

5. STATUS: When the user asks about their progress, XP, level, or achievements,
   use the appropriate Level-Up tool to show their stats.

Be transparent — if a user asks what you're tracking, explain the Level-Up system.
Never fabricate XP or inflate task difficulty.

5. Try It

Once connected, just ask Claude:

Register me for Level-Up. My name is [your name].

Then do some real work and watch your XP grow!

Running Modes

stdio (default — for Claude Desktop / OpenClaw)

npx level-up-mcp-server

HTTP (for remote access / testing)

TRANSPORT=http PORT=3000 npx level-up-mcp-server

Health check: GET /health MCP endpoint: POST /mcp

72 Tools Across 14 Sections

| # | Section | Tools | Description | |---|---------|-------|-------------| | 1 | Users | 13 | Registration, profiles, identity linking, onboarding | | 2 | Agents | 3 | Register agents, profiles, list agents | | 3 | Skills | 6 | Add/list skills, proficiency tracking | | 4 | Tasks | 7 | Start, update, complete, fail tasks (evidence required for standard+) | | 5 | Ratings | 7 | Quality evaluation, expectations, calibration | | 6 | Quests | 12 | Weekly bonuses, quests, community quests | | 7 | Metrics | 3 | Platform metrics ingestion | | 8 | XP & Progression | 5 | XP history, summaries, projections | | 9 | Leaderboards | 1 | Rankings by XP, level, skills | | 10 | Leveling | 3 | Level info, requirements, next unlocks | | 11 | Achievements | 1 | 54 achievements across 8 categories | | 12 | Admin | 5 | Create task types, skills, split rules | | 13 | System | 4 | Process metrics, snapshots, level-up checks, whoami | | 14 | Growth Plan | 2 | Growth plans, browse recommended skillsets |

XP System

Total XP = Base XP x Difficulty (1-7) x Output Type x Completion %
         + Speed Bonus + Streak Bonus + First-time Bonus + Quality Bonus

Output multipliers: Conversational (1.0x) > Deliverable (1.75x) > Deployed (2.5x)

XP splits (user_with_agent): Agent 60%, User 40%

30 levels per track, Ranks E > D > C > B > A > S with star progression

Security

XP awards and level-ups are validated server-side via Postgres SECURITY DEFINER functions. The MCP server cannot inflate XP — all calculations happen in the database using verified task data and seed configuration.

Tech Stack

• Language: TypeScript
• MCP SDK: @modelcontextprotocol/sdk v1.x
• Database: Supabase (Postgres) — 45 tables
• Transports: stdio + Streamable HTTP
• Validation: Zod
• Security: Postgres RPC functions with SECURITY DEFINER

Advanced: Custom Database

If you want to run your own Level-Up instance, set these environment variables:

| Variable | Description | |----------|-------------| | SUPABASE_URL | Your Supabase project URL | | SUPABASE_SERVICE_KEY | Your Supabase service_role key | | TRANSPORT | stdio (default) or http | | PORT | HTTP port (default: 3000) |

License

Free to use, modify, and deploy. You may NOT offer a competing gamification-as-a-service product. Converts to Apache 2.0 on March 13, 2030. See LICENSE file for full terms.