Skip to main content
Glama
compcode-mcp

compcode-mcp

Official
by compcode-ai

@compcode/mcp

The official CompCode MCP server — commission plans as code, as native tools for Claude Code, Cursor, and any Model Context Protocol client.

CompCode is the first commission platform where plans are created, modified, and versioned via API. This server exposes the full plan lifecycle as MCP tools: author plans, assign reps, set quotas, simulate, recalculate, close the month, and export payroll — all from your agent.

Install

You need a CompCode workspace API key (ws_…) from Workspace settings → Integrations → API key.

Claude Code

claude mcp add compcode -e COMPCODE_API_KEY=ws_your_key -- npx -y @compcode/mcp

Cursor / generic mcp.json

{
  "mcpServers": {
    "compcode": {
      "command": "npx",
      "args": ["-y", "@compcode/mcp"],
      "env": { "COMPCODE_API_KEY": "ws_your_key" }
    }
  }
}

Environment variables

Variable

Required

Default

Purpose

COMPCODE_API_KEY

yes*

—

Workspace API key (ws_…). Full workspace-admin access.

COMPCODE_API_URL

no

https://api.compcode.ai

Point at another environment.

* Falls back to ~/.compcode/config.json — shared with the CompCode CLI, so compcode login <ws_…> also configures this server.

Related MCP server: sahmk-mcp

Tools (29)

The same canonical tool contract is also served by CompCode's remote MCP endpoint (POST https://api.compcode.ai/v1/mcp, Streamable HTTP with your ws_… key as a Bearer token) — pick the transport that fits your client.

Plans — list_plans, get_plan (+history, +per-rep overrides), list_plan_templates (8 canonical starters), get_plan_schema (canonical config JSON Schema, no network), create_plan, update_plan (versioned — config changes create a new version), set_rep_overrides

Quotas & assignments — list_quotas, set_quota, delete_quota, list_assignments, assign_plan, unassign_plan

Commissions — simulate_plan (dry run against real deals; per-rep and per-period narrowing), get_commissions_dashboard (team / rep / per-deal trace), recalculate_commissions (rep/plan/workspace scopes run as a background job — a slow recalc returns { status: "running", jobId } instead of timing out), get_recalculation_status

Statements — list_statements, generate_statements, approve_statement (lock/unlock), export_statements (payroll CSV / JSON), add_statement_adjustment, remove_statement_adjustment (confirm-gated)

Discovery — list_deals, list_reps (email search), sync_reps_from_crm, list_fields (CRM field slugs + options), get_workspace, get_audit_log

Plus resources (compcode://schema/plan-config, compcode://templates, compcode://guide) and prompts for the five standard operator flows: connection check, plan authoring, rep onboarding, month close, and commission diagnosis.

Safety model

  • Plan config validation is client-side first. create_plan / update_plan / simulate_plan validate configs against the canonical schema before any network call, returning precise field-level errors.

  • Simulate before you write. Tool descriptions steer agents to simulate_plan before create_plan. Simulation is advisory — it can diverge from the live engine and ignores per-rep overrides.

  • Destructive ops are annotated. approve_statement, unassign_plan, set_rep_overrides, and recalculate_commissions carry destructiveHint so clients can require confirmation.

  • Deliberately not exposed: plan deletion, workspace data reset, deal deletion, API-key regeneration, statement adjustments. Use the dashboard or raw API for those.

  • Rate-limited writes never auto-retry. A 429 on a write returns wait guidance instead of retrying, so an agent can't double-write.

Troubleshooting

Symptom

Fix

401 on every call

COMPCODE_API_KEY isn't a valid ws_… workspace key. Regenerate in workspace settings.

No CompCode API key found on startup

Set COMPCODE_API_KEY in the MCP server's env block, or run compcode login.

429 Rate limited

Workspace tier limits: 120–1200 req/60s; recalculate_commissions 20/60s. Wait and retry.

Wrong environment

Set COMPCODE_API_URL (e.g. a dev instance). The startup line on stderr shows the active URL.

Development

pnpm --filter @compcode/mcp build      # tsc → dist/
pnpm --filter @compcode/mcp test       # vitest (85 tests, no network)
pnpm --filter @compcode/mcp dev        # tsx src/index.ts

# Poke it interactively
npx @modelcontextprotocol/inspector node apps/mcp/dist/index.js

Architecture: src/server.ts + src/tools/* are transport-agnostic and depend only on the CompCodeClient interface — the stdio shell lives entirely in src/index.ts, so the same tool layer can be mounted as a remote streamable-HTTP endpoint later.

Source of truth for this package is the private monorepo (apps/mcp); github.com/compcode-ai/mcp is a public mirror. To re-sync after a change here lands on develop:

git subtree split --prefix=apps/mcp -b mcp-mirror
FILTER_BRANCH_SQUELCH_WARNING=1 git filter-branch -f --env-filter '
  export GIT_AUTHOR_NAME="tech-compcode-ai"    GIT_AUTHOR_EMAIL="tech@compcode.ai"
  export GIT_COMMITTER_NAME="tech-compcode-ai" GIT_COMMITTER_EMAIL="tech@compcode.ai"
' mcp-mirror
git push https://github.com/compcode-ai/mcp.git mcp-mirror:main
git branch -D mcp-mirror

Run the rewrite every time, not just the first. The monorepo's own commits carry individual authors; the public mirror publishes under one project identity. subtree split regenerates the whole branch from monorepo history on each sync, so a sync that skips the rewrite would reintroduce the original authors and fork the hash chain — every later push would then need --force. Applied consistently the rewrite is deterministic (same trees, same dates, same author ⇒ same SHAs), so syncs stay plain fast-forwards.

The mirror carries apps/mcp and nothing above it, so the root mcp-tools.contract.json is absent there and the two cross-transport assertions in server.smoke.test.ts skip. That is expected: the contract binds this package to apps/api/src/mcp, and both are only checkable together — here, via the pre-push hook.

Available Tools

29 tools
add_statement_adjustmentAdd a statement adjustmentA

Add a manual commission adjustment (positive or negative amount) to a rep's statement for a period, with a reason. For the adjust-after-approval flow: first unlock with approve_statement {status:'draft'}, adjust, regenerate, re-approve. Pass an idempotencyKey to make retries safe.

Inputs: repId (required), amount (required), period (required), reason (required), +2 more.

approve_statementApprove or unlock a statementA
DestructiveIdempotent

Approve a rep's statement for a period (status='approved'), or revert it to draft (status='draft') to unlock. ⚠️ Approval LOCKS the statement: recalculations skip this rep+period until reverted to draft. The body is exactly {period, status} — there is no 'approve: true' shorthand.

Inputs: repId (required), period (required), status (required).

assign_planAssign reps to a planA

Assign one or more reps to a plan, optionally bounded by effective dates. Use the plan IDENTITY ID (planId from list_plans), not the version ID. After assigning, set quota targets with set_quota, then recalculate_commissions for the affected reps.

Inputs: planId (required), repIds (required), currency, effectiveEnd, +1 more.

create_planCreate a commission planA

Create a new commission plan (version 1). The config is validated client-side against the canonical plan schema before sending — call get_plan_schema for the shape, or start from list_plan_templates. Recommended: run simulate_plan on the config first to preview payouts. Simulation is ADVISORY — its output can diverge from the live engine and it ignores per-rep tier overrides. After creating: assign reps with assign_plan, set targets with set_quota, then recalculate_commissions.

Inputs: name (required), config (required), currency, effectiveEnd, +2 more.

delete_quotaDelete a quota targetA
DestructiveIdempotent

Delete a single quota row by ID (from list_quotas). Use to remove wrong-period or duplicate quota rows — a rep with no quota for a period has 0% attainment, so tiers won't fire until a correct quota is set.

Inputs: quotaId (required).

export_statementsExport statementsA
Read-onlyIdempotent

Export statements for payroll. Omit repId for the workspace-wide CSV; pass repId for a single rep's export (format 'csv' or 'json' — the JSON shape is the D10 payroll format).

Inputs: repId, format, period.

generate_statementsGenerate statementsA
Idempotent

Generate (or refresh) statement snapshots from live commission events. Omit repIds for all reps, or scope to specific reps. Regenerating a DRAFT statement overwrites it; APPROVED statements are locked and skipped. Typical close flow: generate_statements → review with list_statements → approve_statement → export_statements.

Inputs: period, repIds.

get_audit_logGet audit logA
Read-onlyIdempotent

Get the workspace admin action log (paginated, newest first) — who changed what, when, including every engine (orchestrator) run with its outcome counters. First stop when diagnosing a missing or unexpected commission: pass actor 'orchestrator' + the dealId to answer "did the engine run for this deal?" in one call.

Inputs: actor, limit, dealId, offset.

get_commissions_dashboardGet commissions dashboardA
Read-onlyIdempotent

Commission earnings overview. No params = team overview (all reps). repId = single rep dashboard. dealId = per-deal commission breakdown with the full calculation trace. Set includePeriods to also list the distinct periods that have commission events.

Inputs: repId, dealId, period, includePeriods.

get_planGet a planA
Read-onlyIdempotent

Get a plan version with all rules and tiers. Accepts a planVersionId or a plan identity ID (resolves to the active version). Optionally include the full version history and per-rep tier overrides.

Inputs: planId (required), includeHistory, includeOverrides.

get_plan_schemaGet the plan config schemaA
Read-onlyIdempotent

Get the canonical JSON Schema for the plan config object used by create_plan / update_plan / simulate_plan. No network call. Use this before authoring a config from scratch; use list_plan_templates for ready-made starting points.

Inputs: no named parameters.

get_recalculation_statusGet recalculation job statusA
Read-onlyIdempotent

Check a background recalculation started by recalculate_commissions. status 'running' → poll again in a few seconds; 'completed' → the result field holds the same summary a synchronous recalc returns; 'failed' → see error. Jobs expire after ~6h and don't survive server restarts — if the jobId is unknown, verify the outcome via get_commissions_dashboard or get_audit_log (actor 'orchestrator') instead of re-running the recalculation.

Inputs: jobId (required).

get_workspaceGet workspace infoA
Read-onlyIdempotent

Get workspace info: name, connected CRM + status, field mapping, and subscription tier. Use this as the connection check — if it succeeds, the API key and URL are valid.

Inputs: no named parameters.

list_assignmentsList plan assignmentsA
Read-onlyIdempotent

List rep-to-plan assignments with effective date ranges. Filter by repId or planId.

Inputs: repId, planId.

list_dealsList dealsA
Read-onlyIdempotent

List deal snapshots (latest CRM state per deal) — discover deals without querying the CRM directly. Filter by repId, stage, or since (ISO date). Paginate with limit (max 500) and offset. For a deal's commission breakdown, pass its dealId to get_commissions_dashboard.

Inputs: limit, repId, since, stage, +1 more.

list_fieldsList CRM fieldsA
Read-onlyIdempotent

List the CRM deal field attributes available to plan configs (slug, label, type). Use these slugs for measure, payoutBase, condition fields, etc. Pass slug to fetch the option values of a select/status field (for condition values).

Inputs: slug.

list_plansList commission plansA
Read-onlyIdempotent

List commission plans in the workspace (one row per plan identity; active version preferred). Returns compact rows: planId (identity), planVersionId (version row), name, version, status, effective dates, repCount, and each rule's name — use get_plan for a plan's full config. Set includeConfigs for full configs inline (large).

Inputs: status, allVersions, includeConfigs.

list_plan_templatesList plan templatesA
Read-onlyIdempotent

List CompCode's canonical plan template starters (flat rate, marginal AE, retroactive AE, cascade/manager override, MBO, SDR per-meeting, multi-measure, new-hire ramp). Pass templateId to fetch a single template's full config. Templates are ready-made config objects for create_plan.

Inputs: templateId.

list_quotasList quota targetsB
Read-onlyIdempotent

List quota targets (the grid view). Filter by repId or planId. Period format follows the rule's attainmentPeriod: monthly → YYYY-MM, quarterly → YYYY-QN, annual → YYYY.

Inputs: repId, planId.

list_repsList repsA
Read-onlyIdempotent

List all reps in the workspace (role, active flag, manager, CRM linkage). Pass repId for a single rep's detail including CRM provider, crmId, and sync timestamps. Pass email to search — ALWAYS search by email before assuming a rep doesn't exist.

Inputs: email, repId.

list_statementsList commission statementsA
Read-onlyIdempotent

Get statement data. No repId = team batch view (all reps for the period). With repId = that rep's statement. Set includeStatus (single-rep only) to also fetch the approval status (draft/approved). Statements are frozen snapshots — generate_statements creates/refreshes them from live commission events.

Inputs: repId, period, includeStatus.

recalculate_commissionsRecalculate commissionsA
DestructiveIdempotent

Trigger a live recalculation of commission events. Scope with exactly one of dealId (fastest), repId, or planId — or no scope for the whole workspace (slow; avoid unless necessary). ⚠️ This REWRITES commission events for the scope (history is preserved in the audit trail). Approved statements are locked and skipped. Rep/plan/workspace scopes run as a background job: if the result isn't ready in ~45s you get { status: 'running', jobId } — the recalc has NOT failed; do NOT retry, poll get_recalculation_status instead. Rate limit: 20 requests per 60s.

Inputs: repId, dealId, planId.

remove_statement_adjustmentRemove a statement adjustmentA
DestructiveIdempotent

Hard-delete a manual adjustment from a rep's statement (engine-written commission events are unaffected). This permanently removes a financial record — requires confirm: true.

Inputs: repId (required), confirm (required), adjustmentId (required).

set_quotaSet quota targetsA
Idempotent

Set (upsert) quota targets for one or more reps. Period format must match the rule's attainmentPeriod (monthly → '2026-07', quarterly → '2026-Q3', annual → '2026'). Use measure with the rule NAME from the plan config (the API resolves it to the plan rule). variableTarget sets the rep's variable comp (OTE) used by payoutBase='variable_target' rules.

Inputs: repIds (required), target (required), period, planId, +5 more.

set_rep_overridesSet per-rep tier overridesA
DestructiveIdempotent

Set per-rep tier rate overrides on a plan version (same plan, different rates for one rep), or clear them with clear=true to revert the rep to global rates. Get ruleId/tierIndex values from get_plan. Note: simulate_plan ignores overrides — verify with recalculate + dashboard.

Inputs: repId (required), planVersionId (required), clear, rules.

simulate_planSimulate a plan (dry run)A
Read-onlyIdempotent

Dry-run the commission engine against real workspace deals WITHOUT persisting anything. Pass either a full planConfig (pre-flight a new design) or a planId (existing plan). period accepts a specific period or 'all' (buckets each deal by its own close-date period); repId narrows to one rep. ⚠️ ADVISORY ONLY: simulation output can diverge from the live engine and it IGNORES per-rep tier overrides. Use it to sanity-check plan structure and rough magnitudes, not to certify exact payouts.

Inputs: repId, period, planId, planConfig.

sync_reps_from_crmSync reps from CRMA
Idempotent

Pull the latest rep roster from the connected CRM into the workspace (upsert — never deletes). Run when a rep is missing from list_reps: reps only exist in CompCode via CRM sync.

Inputs: no named parameters.

unassign_planRemove a plan assignmentA
Destructive

Unlink a rep from a plan by assignment ID (from list_assignments). Historical commission events are NOT deleted — only future calculation stops. To reverse earned commissions, use recalculate_commissions after unassigning.

Inputs: assignmentId (required).

update_planUpdate a commission planA

Update a plan's config, effective dates, currency, or status. Config/date changes create a NEW plan version (append-only history — nothing is lost). Status-only changes (active/archived) transition the version in place. Recommended: run simulate_plan on the config first to preview payouts. Simulation is ADVISORY — its output can diverge from the live engine and it ignores per-rep tier overrides.

Inputs: planRef (required), config, status, currency, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 29 tools

    Disambiguation4/5

    Most tools have clear resource/action separation, and the descriptions clarify boundaries between plans, assignments, quotas, statements, and recalculation. Some overlap remains among reporting/export tools (get_commissions_dashboard, list_statements, generate_statements, export_statements) and between simulate_plan and recalculate_commissions, requiring careful tool selection.

    Naming Consistency5/5

    Tool names consistently use snake_case with predictable verb_noun patterns such as list_plans, create_plan, set_quota, approve_statement, and remove_statement_adjustment. Minor exceptions like get_recalculation_status still fit the same convention.

    Tool Count3/5

    The 29-tool surface is heavy, even for a broad commission-management domain. Each tool maps to a meaningful operation, but several reporting and statement-related tools could potentially be consolidated to reduce selection burden.

    Completeness4/5

    The server covers the core commission lifecycle well: plan creation/update, assignment, quotas, simulation, recalculation, statements, approvals, exports, adjustments, audit, and CRM rep sync. Minor gaps include no explicit plan deletion tool and rep creation/update being delegated to CRM sync rather than direct tools.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      MCP server for managing affiliate and referral programs. Track referrals, manage affiliates, process conversions, and handle payouts through AI assistants like Claude, Cursor, and ChatGPT.
      18
      238 npm
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Official MCP server for interacting with Saudi market data (Sahmk) via natural language queries, enabling stock quotes, company info, and market summaries inside AI agents like Cursor and Claude Desktop.
      15
      56 PyPI
      15
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Official MCP server for Scorezilla (leaderboards for games). Your AI coding assistant can bootstrap a leaderboard, inspect games and boards, read top-N standings, and paste ready-to-run SDK integration code — without leaving the editor.
      11
      62 npm
      1
      MIT