Model Context Protocol (MCP) Integration Guide

Connect CodePeel's AI code review engine to Claude Code, Cursor, Windsurf, Cline, Roo Code, Claude Desktop, and all MCP-compatible AI agents.

Once configured, your agent can review unified diffs before you commit, suggest targeted bug and security fixes, explain architectural nuances, and check review allowances — all powered by the same multi-engine analyzer as our GitHub App and VS Code extension.

1. Prerequisites

1. CodePeel Account & API Token:
   • Sign in to your dashboard and generate an API key at Settings → MCP Tokens.
   • CodePeel MCP tokens begin with the cpk_ prefix. Treat this token as a secret and avoid committing it to version control.
2. Node.js Environment:
   • Requires Node.js 18 or newer (node -v).
   • Uses npx to run @codepeelai/codepeel on demand with zero manual installation.

2. Platform Setup Matrix

Select your agent or editor below for exact setup instructions and configuration snippets.

Claude Code CLI

Register CodePeel directly using the Claude Code CLI:

macOS & Linux (bash / zsh)

claude mcp add codepeel --env CODEPEEL_TOKEN=cpk_your_token_here -- npx -y @codepeelai/codepeel

Windows (PowerShell)

claude mcp add codepeel --env CODEPEEL_TOKEN=cpk_your_token_here "--" npx -y @codepeelai/codepeel

Shared Team Configuration (.mcp.json)

To share CodePeel across your entire engineering team via version control, create an .mcp.json file in your repository root:

{
  "mcpServers": {
    "codepeel": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@codepeelai/codepeel"],
      "env": {
        "CODEPEEL_TOKEN": "cpk_your_token_here"
      }
    }
  }
}

Cursor AI

Cursor supports MCP servers both through its visual settings and via workspace configuration.

Option A: Workspace Configuration File (.cursor/mcp.json)

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

{
  "mcpServers": {
    "codepeel": {
      "command": "npx",
      "args": ["-y", "@codepeelai/codepeel"],
      "env": {
        "CODEPEEL_TOKEN": "cpk_your_token_here"
      }
    }
  }
}

[!TIP] On Windows, if Cursor cannot locate npx in its GUI process environment, change "command": "npx" to "command": "npx.cmd".

Option B: Settings UI

1. Open Cursor Settings (Ctrl+, or Cmd+,).
2. Navigate to Features → MCP.
3. Click + Add New MCP Server.
4. Configure:
   • Name: codepeel
   • Type: stdio
   • Command: npx -y @codepeelai/codepeel
   • Add environment variable CODEPEEL_TOKEN with your cpk_... value.

Claude Desktop (GUI App)

Claude Desktop reads from a local JSON configuration file.

Configuration File Locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add codepeel under mcpServers:

{
  "mcpServers": {
    "codepeel": {
      "command": "npx",
      "args": ["-y", "@codepeelai/codepeel"],
      "env": {
        "CODEPEEL_TOKEN": "cpk_your_token_here"
      }
    }
  }
}

Restart Claude Desktop after saving the configuration file.

Windsurf / Cascade (Codeium)

Windsurf stores global MCP registrations in a dedicated JSON file.

Configuration File Locations:

• macOS / Linux: ~/.windsurf/mcp.json (or ~/.codeium/windsurf/mcp_config.json)
• Windows: %APPDATA%\Windsurf\mcp.json

{
  "mcpServers": {
    "codepeel": {
      "command": "npx",
      "args": ["-y", "@codepeelai/codepeel"],
      "env": {
        "CODEPEEL_TOKEN": "cpk_your_token_here"
      }
    }
  }
}

Cline & Roo Code (VS Code Extensions)

1. Open the Cline or Roo Code extension panel in VS Code.
2. Click the MCP Servers (plug) icon and choose Configure MCP Servers.
3. Edit cline_mcp_settings.json:

{
  "mcpServers": {
    "codepeel": {
      "command": "npx",
      "args": ["-y", "@codepeelai/codepeel"],
      "env": {
        "CODEPEEL_TOKEN": "cpk_your_token_here"
      }
    }
  }
}

Zed Editor

Zed configures MCP context servers in its user or project settings.json under the "context_servers" key:

{
  "context_servers": {
    "codepeel": {
      "command": "npx",
      "args": ["-y", "@codepeelai/codepeel"],
      "env": {
        "CODEPEEL_TOKEN": "cpk_your_token_here"
      }
    }
  }
}

Continue.dev

Continue uses an array-based schema in ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "codepeel",
      "command": "npx",
      "args": ["-y", "@codepeelai/codepeel"],
      "env": {
        "CODEPEEL_TOKEN": "cpk_your_token_here"
      }
    }
  ]
}

OpenCode Interpreter & LibreChat

OpenCode (opencode.json):

{
  "mcp": {
    "codepeel": {
      "type": "local",
      "command": ["npx", "-y", "@codepeelai/codepeel"],
      "enabled": true,
      "environment": {
        "CODEPEEL_TOKEN": "cpk_your_token_here"
      }
    }
  }
}

LibreChat (librechat.yaml):

mcpServers:
  codepeel:
    type: stdio
    command: npx
    args:
      - -y
      - '@codepeelai/codepeel'
    env:
      CODEPEEL_TOKEN: 'cpk_your_token_here'

3. Platform Comparison Reference

4. Verification & Testing

Verify that your CodePeel token is valid and test your connection directly from your terminal:

# Verify balance and connection directly without consuming quota
npx -y @codepeelai/codepeel credits

(If CODEPEEL_TOKEN is set in your shell environment, this outputs your active tier and remaining review quota.)

In Claude Code, run:

claude mcp list

You should see codepeel with status Connected and its 10 tools exposed.

5. Available Tools & Prompts

Tools

review_code

Performs a deep review on a unified diff against bug risks, logic flaws, OWASP vulnerabilities, and regression hazards.

• diff (string, required): The unified diff to review (minimum 10 characters).
• repo (string, optional): Repository name or context slug.

fix_code

Generates an immediate code fix for a specific finding or security alert.

• file (string, required): The target file path.
• issue (string, required): The issue description or vulnerability.
• problemCode (string, optional): Surrounding code snippet.
• line (number, optional): Line number.
• severity (string, optional): critical, high, medium, or low.

ask_codepeel

Queries CodePeel regarding architectural decisions, security implications, or potential regressions for proposed changes.

• question (string, required): The architectural or security inquiry.
• diff (string, optional): Relevant diff or patch context.

check_credits

Checks your current plan, monthly quota, and remaining review allowance. Free of charge (does not consume reviews).

Review history tools

These read saved PR reviews and do not consume review credits. Start with list_workspaces to discover workspace IDs and your role.

Owners and admins can read their team's reviews. Members can read their own reviews; pending or removed members cannot read team data. Search tools return a nextCursor for pagination. Review status is CodePeel's processing status, not the live GitHub PR state. A finding may already have been fixed.

Built-in Prompts

• review-staged-changes: Instructs the agent to gather uncommitted or staged git changes and review them with CodePeel before creating a commit.
• security-audit: Focuses specifically on OWASP Top 10 vulnerabilities, injection vectors, and auth flaws.
• explain-and-fix: Explains the crux of a bug finding and automatically applies the patch.

6. Common Pitfalls & Troubleshooting

• PowerShell error: unknown option '-y': PowerShell removes naked -- delimiters. Quote the delimiter as "--" when executing claude mcp add in PowerShell.
• Always Keep the -y Flag with npx: Without -y / --yes, npx prompts interactively on first launch (Ok to proceed? (y)). Any interactive prompt writes to stdout and corrupts the stdio JSON-RPC handshake stream.
• Windows GUI PATH Resolution: Some GUI applications (Claude Desktop, Cursor) do not inherit user shell PATH variables. If an app reports that npx cannot be found on Windows, use "npx.cmd" or install the package globally via npm install -g @codepeelai/codepeel.