compcode-mcp
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., "@compcode-mcp Simulate commissions for the new plan I drafted."
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.
@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/mcpCursor / generic mcp.json
{
"mcpServers": {
"compcode": {
"command": "npx",
"args": ["-y", "@compcode/mcp"],
"env": { "COMPCODE_API_KEY": "ws_your_key" }
}
}
}Environment variables
Variable | Required | Default | Purpose |
| yes* | — | Workspace API key ( |
| no |
| 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_planvalidate configs against the canonical schema before any network call, returning precise field-level errors.Simulate before you write. Tool descriptions steer agents to
simulate_planbeforecreate_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, andrecalculate_commissionscarrydestructiveHintso 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 |
|
|
| Set |
| Workspace tier limits: 120–1200 req/60s; |
Wrong environment | Set |
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.jsArchitecture: 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-mirrorRun 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.
Links
Agent guide: https://compcode.ai/CLAUDE.md
Available Tools
29 toolsadd_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 statementADestructiveIdempotent
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 targetADestructiveIdempotent
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 statementsARead-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 statementsAIdempotent
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 logARead-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 dashboardARead-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 planARead-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 schemaARead-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 statusARead-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 infoARead-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 assignmentsARead-onlyIdempotent
List rep-to-plan assignments with effective date ranges. Filter by repId or planId.
Inputs: repId, planId.
list_dealsList dealsARead-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 fieldsARead-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 plansARead-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 templatesARead-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 targetsBRead-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 repsARead-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 statementsARead-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 commissionsADestructiveIdempotent
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 adjustmentADestructiveIdempotent
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 targetsAIdempotent
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 overridesADestructiveIdempotent
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)ARead-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 CRMAIdempotent
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 assignmentADestructive
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
Scored across 29 tools
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.
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.
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.
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
Related MCP Connectors
Official MCP server for subfeed.app — the cloud for agents. 15+ tools for AI agents to register, build, and deploy other agents. Zero human required. Start here: subfeed.app/skill.md
Official MCP server for OmniDimension. Drive voice agents, dispatch calls, and run bulk campaigns.
Official Miro MCP server - Supports context to code and creating diagrams, docs, and data tables.
Official MCP server for Lovable, the AI-powered full-stack app builder.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server for managing affiliate and referral programs. Track referrals, manage affiliates, process conversions, and handle payouts through AI assistants like Claude, Cursor, and ChatGPT.18238 npm2MIT
- AlicenseAqualityCmaintenanceOfficial 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.1556 PyPI15MIT
- AlicenseAqualityBmaintenanceOfficial 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.1162 npm1MIT
- AlicenseNot gradedqualityCmaintenancePublic MCP server for integrating Cuprice pricing widgets from AI tools like Cursor, Claude Desktop, and Claude Code.1MIT