@levell/mcp-server

An MCP (Model Context Protocol) server that lets AI assistants — Claude Desktop, Cursor, Windsurf, GitHub Copilot, and any MCP-compatible client — interact with your Levell workspace.

50 tools across workspace, employees, framework, assessments, insights, and growth plans. Docs and setup guide: getlevell.com/integrations.

Once configured, Claude can answer questions like:

• "Who on the team is currently rated as Mastering in System Design?"
• "Create a Q2 2026 assessment for Sarah and rate her as Matching in all Backend competencies."
• "What does our team's rating distribution look like across Framework categories?"

Prerequisites

• Node.js 18+
• A Levell workspace on the Pro plan or above
• An API key from Workspace Settings → API Keys

Quick start

1. Generate an API key

In Levell, go to Workspace Settings → API Keys and click Create API key. Copy the key — it's shown only once.

2. Configure Claude Desktop

Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) and add:

{
  "mcpServers": {
    "levell": {
      "command": "npx",
      "args": ["-y", "@levell/mcp-server"],
      "env": {
        "LEVELL_API_KEY": "lv_your_key_here",
        "LEVELL_WORKSPACE_ID": "your-workspace-id"
      }
    }
  }
}

Restart Claude Desktop. You should see the Levell tools appear in the tool picker.

HTTP transport (no local install)

Connect directly to your Levell workspace via the Streamable HTTP endpoint using mcp-remote:

{
  "mcpServers": {
    "levell": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://getlevell.com/api/workspace/YOUR_WORKSPACE_ID/mcp",
        "--header",
        "Authorization:${LEVELL_AUTH}"
      ],
      "env": {
        "LEVELL_AUTH": "Bearer lv_your_key_here"
      }
    }
  }
}

Read-only API keys only expose list/get/insights tools — write tools are hidden at the MCP layer.

3. Configure Cursor

Add to .cursor/mcp.json in your project or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "levell": {
      "command": "npx",
      "args": ["-y", "@levell/mcp-server"],
      "env": {
        "LEVELL_API_KEY": "lv_your_key_here",
        "LEVELL_WORKSPACE_ID": "your-workspace-id"
      }
    }
  }
}

4. Configure Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "levell": {
      "command": "npx",
      "args": ["-y", "@levell/mcp-server"],
      "env": {
        "LEVELL_API_KEY": "lv_your_key_here",
        "LEVELL_WORKSPACE_ID": "your-workspace-id"
      }
    }
  }
}

Environment variables

| Variable | Required | Description | |---|---|---| | LEVELL_API_KEY | ✅ | Workspace API key (lv_...) | | LEVELL_WORKSPACE_ID | ✅ | Your workspace slug or ID |

Local development & inspect mode

When working in the Levell monorepo, build and run the stdio server locally:

# From repo root
pnpm --filter @levell/mcp-server build
LEVELL_API_KEY=lv_... LEVELL_WORKSPACE_ID=your-workspace-id \
  node packages/mcp-server/dist/index.js

MCP Inspector (recommended for debugging)

Use the built-in inspect script to launch the MCP Inspector — a local web UI to list tools, run calls, and debug prompts without Claude Desktop or Cursor:

# From repo root
LEVELL_API_KEY=lv_... LEVELL_WORKSPACE_ID=your-workspace-id pnpm mcp:inspect

# Or from packages/mcp-server
cd packages/mcp-server
LEVELL_API_KEY=lv_... LEVELL_WORKSPACE_ID=your-workspace-id pnpm inspect

inspect runs pnpm build first, then starts mcp-inspector against dist/index.js. The Inspector URL prints in the terminal (typically http://localhost:6274).

Watch mode while editing server code:

pnpm --filter @levell/mcp-server dev   # tsc --watch in another terminal

Re-run pnpm inspect after changes (or restart the inspector session).

Programmatic use

The package also exports server factories for embedding in other Node apps:

import { createLevellMcpServer, makeApiRequest } from "@levell/mcp-server";

See src/programmatic.ts for exports.

Available tools

Workspace

| Tool | Description | |---|---| | get_workspace | Get workspace metadata: name, plan, and feature flags |

Employees

| Tool | Description | |---|---| | list_employees | List all employees with level, track, org unit, and manager | | find_employees | Search employees by name substring (prefer over scanning the full list) | | get_employee | Get an employee's profile, assessments, and rating history | | create_employee | Add a new employee to the workspace | | update_employee | Update an employee's profile fields |

Framework

| Tool | Description | |---|---| | get_framework | Get the full active framework: levels, tracks, categories, competencies, expectations | | list_levels | List all levels | | create_level | Create a new level | | update_level | Update a level's name or description | | delete_level | Delete a level | | list_tracks | List all tracks | | create_track | Create a new track | | update_track | Update a track | | delete_track | Delete a track | | list_categories | List all categories | | create_category | Create a new category | | update_category | Update a category | | delete_category | Delete a category | | list_competencies | List all competencies | | create_competency | Create a new competency | | update_competency | Update a competency | | delete_competency | Delete a competency | | get_expectations | Get all expectations for a competency | | upsert_expectation | Create or update an expectation for a specific level | | delete_expectation | Delete an expectation |

Assessments & Evaluations

| Tool | Description | |---|---| | list_assessments | List all assessments, optionally filtered by employee | | list_evaluation_periods | List the valid evaluation periods shown in the UI | | get_assessment | Get full assessment detail: ratings per competency + AI analysis | | get_competency | Get a single competency and its expectations | | create_assessment | Create a new manager or self assessment | | rate_competency | Add/update a competency rating (Learning / Matching / Mastering) | | bulk_rate_competencies | Rate multiple competencies in a single call | | generate_assessment_analysis | Trigger AI analysis for a submitted assessment | | submit_assessment | Mark an assessment as completed |

Insights

| Tool | Description | |---|---| | get_team_insights | Aggregate team data: rating distribution, level distribution, recent assessments |

Growth plans

| Tool | Description | |---|---| | list_growth_cycles | List all growth cycles, optionally filtered by employee | | get_growth_cycle | Get full cycle detail: signals and check-in history | | create_growth_cycle | Create a growth cycle linked to an assessment analysis | | update_cycle_status | Set a cycle to active, paused, or completed | | delete_growth_cycle | Delete a growth cycle | | list_growth_signals | List growth signals for a cycle | | create_growth_signal | Manually add a growth signal to a cycle | | update_growth_signal | Update a signal's text | | delete_growth_signal | Remove a signal from a cycle | | extract_growth_signals | Use AI to extract growth signals from an assessment analysis | | list_check_ins | List check-in periods for a cycle | | get_check_in | Get a check-in with all signal responses | | open_next_check_in | Open the next check-in period for a cycle | | submit_check_in_responses | Submit manager or IC responses to a check-in |

Example AI workflows

Run a full evaluation cycle:

Create a Q3 2026 assessment for Alex → rate all Backend competencies →
generate an analysis → extract growth signals → create a monthly growth cycle

Team health check:

What's our team's rating distribution across Framework categories?
Who is below Matching in more than two competencies?

Build or edit the framework:

Add a new competency called "Incident Management" to the Reliability category at the Senior level
with an expectation of "Leads postmortems and drives systemic fixes"

Key scopes

When creating an API key you choose a scope:

• Read & write — all 50 tools available
• Read only — list_*, get_*, find_*, get_team_insights only; write tools are not registered

MCP prompts

| Prompt | Description | |---|---| | run_evaluation_cycle | Guided workflow: assess → rate → submit → analyse → extract signals | | start_growth_plan | Create a growth cycle from an existing analysis | | team_health_check | Summarize rating distribution and gaps |

Publishing

The package is public and scoped as @levell/mcp-server. You need npm package creation/publish access in the @levell organization and must be signed in. Verify both before releasing:

npm login
npm whoami

If npm whoami succeeds but publishing still returns 404, the signed-in account is not an owner or member with package-creation permission in the @levell organization. An organization owner must grant that access, or create the organization first if the scope does not yet exist.

From the repository root:

# 1. Typecheck, test, build, and inspect the npm tarball contents
pnpm mcp:pack

# 2. Bump the package version (choose patch, minor, or major)
pnpm --filter @levell/mcp-server version:patch

# 3. Preview npm's publish operation without releasing
pnpm mcp:publish:dry-run

# 4. Publish the public package
pnpm mcp:publish

mcp:publish runs the package's prepublishOnly hook, which repeats typecheck, tests, and build before npm accepts the release. Version scripts update the MCP package's package.json without creating a Git commit or tag, so the release change can be reviewed and committed normally.

Equivalent commands from packages/mcp-server are npm run pack:check, npm run publish:npm:dry-run, and npm run publish:npm.

The package is published as @levell/mcp-server on npm.

Security

• API keys are hashed with SHA-256 before storage — the plaintext is shown only once and is never recoverable.
• Keys are scoped per workspace — a key for workspace A cannot access workspace B.
• last_used_at is updated on every successful request for audit purposes.
• Keys can be revoked at any time from Settings → API Keys.