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

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.

Links

• Docs: https://compcode.ai/docs.html
• Agent guide: https://compcode.ai/CLAUDE.md
• OpenAPI: https://api.compcode.ai/v1/openapi.json