MCP Server Setup Guide

What is the Commish MCP Server?

The Commish MCP (Model Context Protocol) server lets you manage your entire commission tracking workflow through natural language. Instead of clicking through the dashboard, just tell your AI assistant what you need:

• *"Show me all pending deals"*
• *"What would Sarah earn if she closes a $150K deal?"*
• *"Create a Q3 SPIFF — $500 per new logo over $10K"*
• *"Clone Phil's comp plan and bump accelerators by 2%"*

It works with Claude Desktop, Claude Code, ChatGPT, Cursor, and any MCP-compatible AI client.

Prerequisites

• Node.js 18+ installed on your machine
• A Commish account with API access enabled
• An MCP-compatible AI client

Step 1: Generate Your API Key

• Log in to Commish at app.getcommish.io
• Navigate to Admin → Settings → API Keys
• Click "Create API Key"
• Name your key (e.g., "Claude Desktop MCP") and select scopes:

• Copy your key. It will look like: cm_live_a1b2c3d4e5f6...

⚠️ Important: Store your API key securely. It provides direct access to your commission data. Never share it publicly or commit it to version control.

Step 2: Configure Your AI Client

Claude Desktop (macOS)

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

`json

{

"mcpServers": {

"commish": {

"command": "npx",

"args": ["-y", "commish-mcp-server"],

"env": {

"COMMISH_API_KEY": "cm_live_your_api_key_here"

}

}

}

}

`

Claude Desktop (Windows)

Edit %APPDATA%\Claude\claude_desktop_config.json with the same configuration as above.

Claude Code

`bash

# Add the MCP server

claude mcp add commish -- npx -y commish-mcp-server

# Set your API key in your environment

export COMMISH_API_KEY="cm_live_your_api_key_here"

`

Cursor

Create or edit .cursor/mcp.json in your project root:

`json

{

"mcpServers": {

"commish": {

"command": "npx",

"args": ["-y", "commish-mcp-server"],

"env": {

"COMMISH_API_KEY": "cm_live_your_api_key_here"

}

}

}

}

`

Local Development (from source)

`bash

git clone https://github.com/commish-io/commish-mcp-server

cd commish-mcp-server

npm install

npm run build

COMMISH_API_KEY="cm_test_your_key" node dist/index.js

`

Step 3: Verify the Connection

After configuring, restart your AI client. You should see 28 Commish tools available. Try a simple command:

Try it: "List all my sales reps" — this should return your team from Commish.

Available Tools (28 Total)

Deals (6 tools)

Comp Plans (6 tools)

Users (5 tools)

Commissions (3 tools)

SPIFFs (5 tools)

Webhooks (3 tools)

Example Conversations

Environment Variables

Rate Limits

The Commish API allows 100 requests per minute per API key. The MCP server automatically retries with exponential backoff if you hit the limit. Under normal conversational use, you'll never come close to this limit.

Troubleshooting

"Authentication failed"

• Verify your COMMISH_API_KEY is set correctly in your client config
• Check that the key starts with cm_live_ or cm_test_
• Confirm the key hasn't been revoked in Admin → Settings → API Keys

"Insufficient scope"

• Your API key doesn't have the required permission for that action
• Write operations need write scope; management actions need admin
• Generate a new key with broader scopes if needed

"No tools showing in my AI client"

• Restart your AI client after editing the config file
• Verify the JSON config is valid (no trailing commas, proper quotes)
• Check that npx is available in your PATH
• Try running manually: COMMISH_API_KEY=your_key npx -y commish-mcp-server

Security Best Practices

• Use test keys (cm_test_) during development and evaluation
• Use the minimum scope needed — if you only need to view data, use read
• Rotate keys periodically via Admin → Settings → API Keys
• Never commit API keys to version control — use environment variables
• Set key expiration dates for temporary integrations