MCP Server

The CodePeel MCP server exposes AI code review as a set of tools and reusable prompts that any MCP-compatible AI coding agent can call. Your AI writes code, then reviews its own output for bugs and security issues before presenting it to you. The server runs locally via npx and communicates with the CodePeel review API over HTTPS.

Compatible with Kiro, Claude Code, Cursor, Cline, Roo (VS Code), and any client that implements the Model Context Protocol.

---

Prerequisites

Before setting up the MCP server, you need a CodePeel account.

Create an account

Sign up at codepeel.com using GitHub, Google, or email. A free account provides 30 reviews per month, which is sufficient for testing the MCP integration. No credit card is required.

---

Setup

The MCP server is distributed via npm and runs via npx. No global installation is required. The server starts in stdio mode, which is the standard transport for MCP servers communicating with AI editors.

Quick Setup (Recommended)

The easiest way to install across all editors on your system is using add-mcp:

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

This automatically:

1. Detects all MCP-compatible editors installed on your system (Cursor, Claude Desktop, Windsurf, Zed, etc.)
2. Writes the server configuration with your CODEPEEL_TOKEN injected for all editors.

Supported Editors

CodePeel MCP works with 17+ editors including:

• Claude Code, Claude Desktop
• Cursor, VS Code
• Cline, Roo, Kilo Code
• Gemini CLI, Codex, Goose
• Windsurf, Zed, OpenCode

Manual Configuration

Add the CodePeel server to your editor's MCP configuration file. Get your API token from Settings → MCP Tokens.

Kiro

Add to .kiro/settings/mcp.json in your workspace:

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

Claude Code

Run the claude mcp add command:

claude mcp add codepeel -e CODEPEEL_TOKEN=cpk_your_api_token_here -- npx -y @codepeelai/codepeel

Or add to the Claude Desktop configuration file (claude_desktop_config.json):

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

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

Cursor

Add to .cursor/mcp.json in your project root:

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

Cline / Roo / Other Extensions

1. Open the extension's MCP settings UI
2. Add a new server with the following details:
   • Server name: codepeel
   • Command: npx
   • Args: -y @codepeelai/codepeel
   • Env: CODEPEEL_TOKEN = cpk_your_api_token_here

Alternatively, edit the settings file directly:

• Cline: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Roo: ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json

---

Authentication

CodePeel MCP uses persistent API tokens (cpk_...) created from your dashboard settings.

Step 1: Create an API Token

1. Log in to codepeel.com and navigate to Settings → MCP Tokens.
2. Click Create API Token.
3. Copy your generated token (starts with cpk_...).

Step 2: Set CODEPEEL_TOKEN

Add the token to your MCP configuration file under "env":

"env": {
  "CODEPEEL_TOKEN": "cpk_your_api_token_here"
}

Or set it in your shell environment:

export CODEPEEL_TOKEN="cpk_your_api_token_here"

---

Available Tools

Once connected, your AI agent has access to four tools. Each tool is registered with the MCP protocol and appears in your agent's tool list automatically.

review_code

Reviews a unified diff for bugs, security issues, and best practice violations. This is the primary tool and uses the same analysis as GitHub PR reviews (secret scanning, AI analysis, SAST, and architecture review).

The tool checks your credit balance before making the review call. If you have no reviews remaining, it returns an error with upgrade instructions instead of consuming a failed request.

Response format:

The tool returns a Markdown-formatted report containing:

• A summary line
• Each finding with severity icon, title, file location, explanation, and suggested fix code block
• Aggregate metrics (bugs, security issues, architecture findings)

Example output:

## Code Review Results

**Summary:** Found 2 issues in the payment module.

### 🔴 SQL Injection in getUserById
**File:** src/db/users.ts:42 | **Severity:** critical | **Type:** security

User input is concatenated directly into the SQL query string,
allowing an attacker to inject arbitrary SQL commands.

**Suggested fix:**
const result = await db.query('SELECT * FROM users WHERE id = $1', [userId]);

---

### 🟡 Missing error handler on async call
**File:** src/api/payments.ts:18 | **Severity:** medium | **Type:** bug

The promise returned by processPayment() is not awaited or caught,
which means rejections will be silently swallowed.

**Suggested fix:**
try {
  await processPayment(order);
} catch (err) {
  logger.error('Payment failed', { orderId: order.id, error: err });
  throw err;
}

---

**Metrics:** 1 bugs, 1 security, 0 architecture

---

fix_code

Generates a fix for a specific code issue. Provide the file path and a description of the problem, and the tool returns a patch with an explanation. This is useful when your AI agent has identified an issue and needs a concrete fix.

Response format:

Returns a Markdown report with the file path, generated fix code in a fenced code block, and a description of what the fix does.

---

ask_codepeel

Ask questions about code patterns, architecture, or get explanations. This tool provides a conversational interface to the CodePeel AI, optionally with code context. Use it for architecture advice, code explanations, or to explore alternatives.

Response format:

Returns the AI-generated answer as plain text. The response is informed by the provided code context and your repository's learned patterns.

---

check_credits

Check your account balance, plan tier, and usage for the current billing period. This tool is free and does not consume a review from your quota.

Response format:

Returns a Markdown summary with your plan tier, a usage progress bar, reviews used and remaining (or "Unlimited" for Max), reset date, and account/organization name. Includes a warning if your balance is low or exhausted, and notes if your subscription is set to cancel.

Example output:

## CodePeel Account

**Account:** @yourname

**Plan:** Pro

| Metric | Value |
|---|---|
| **Usage** | 127 / 500 reviews (25%) |
| **Progress** | `█████░░░░░░░░░░░░░░░` |
| **Remaining** | 373 reviews — ✅ 373 available |
| **Resets** | Jul 1, 2026 |

---

Available Prompts

In addition to tools, the server exposes three reusable prompts. Your AI agent can load a prompt to get a structured workflow instruction, then execute it using the tools. Prompts do not consume reviews — only the tool calls they trigger do.

review-staged-changes

Pre-commit review workflow. Instructs the agent to run git diff --cached, pass the output to review_code, and report all findings.

No arguments.

security-audit

Security-focused review. Instructs the agent to get the diff, run review_code, then evaluate findings through a security lens — prioritizing injection, secrets, auth flaws, and unsafe data handling. For critical/high security findings, it also calls fix_code to generate secure fixes.

No arguments.

explain-and-fix

Full review cycle. Instructs the agent to review the diff, explain each finding in plain language with impact analysis, generate fixes with fix_code, and apply them. Sorted by severity.

Using prompts

Most MCP clients allow you to select a prompt from a list. When selected, the prompt returns a user message that the agent follows. For example, selecting review-staged-changes before a commit tells the agent to automatically review your staged changes.

---

How It Works

The MCP server follows the Model Context Protocol specification for tool-based communication between AI agents and external services.

Request flow

1. Your AI agent decides to call a CodePeel tool (e.g., review_code)
2. The editor sends a tool call to the MCP server
3. The server authenticates via your CODEPEEL_TOKEN API token
4. For review_code, fix_code, and ask_codepeel, the server first checks your credit balance
5. If credits are available, the server makes the API call
6. The response is formatted as Markdown and returned to the agent

Credit checking

Before making expensive API calls (review_code, fix_code, ask_codepeel), the server pre-checks your credit balance. If you have no reviews remaining, it returns a descriptive error immediately without consuming a failed request. This prevents wasted API calls and provides clear upgrade guidance.

Max-tier users still hit the 5000/month abuse cap (see Billing).

Error handling

The server handles all common error scenarios and returns user-friendly messages:

---

Review Consumption

Each tool call that triggers AI analysis consumes 1 review from your quota. The check_credits tool is always free. All MCP tool calls draw from the same pool as GitHub PR reviews and VS Code extension reviews. See Billing for full details on plans and quotas.

Rate limits

MCP tool calls draw from your plan's review quota and rate limits. The check_credits tool is always free and does not consume reviews. See Billing for full plan details.

---

Common Workflows

Self-reviewing AI code

The most powerful pattern is having your AI agent review its own output before presenting it to you. This catches bugs, security issues, and logic errors that the AI might introduce during code generation.

You: Build a user authentication middleware
AI: [writes the middleware code]
AI: [calls review_code with the diff of its changes]
AI: CodePeel found a timing attack vulnerability in the password
    comparison. Let me fix that with a constant-time comparison...
AI: Here's the corrected middleware with crypto.timingSafeEqual.

This workflow is especially effective because the AI has full context about what it intended to write, making it easy to apply fixes immediately.

Pre-commit quality gate

Use the MCP server as a pre-commit check by asking your AI to review staged changes:

You: Review my staged changes before I commit
AI: [runs git diff --cached, passes output to review_code]
AI: Found 3 issues:
    - Critical: Hardcoded API key in config.ts
    - High: Missing null check in user lookup
    - Medium: Unused import in utils.ts
    Should I fix these before you commit?

Targeted fix generation

When you know about a specific issue, use fix_code to generate a targeted fix:

You: Fix the N+1 query problem in src/services/orders.ts line 45
AI: [calls fix_code with file, issue description, and line number]
AI: Here's the fix — I've replaced the loop with a batched query
    so the data is fetched in a single round-trip...

Architecture consultation

Use ask_codepeel for high-level questions about your codebase:

You: Ask CodePeel if there are race conditions in my auth flow
AI: [calls ask_codepeel with the question and relevant code as diff]
AI: CodePeel identified a potential race condition between the token
    refresh and the API call. If the refresh completes after the call
    starts, the request uses a stale token...

Continuous review during development

Configure your AI agent to automatically review after generating code. Many agents support system prompts or rules that can include instructions like:

After writing or modifying code, always call review_code with the
changes to check for bugs and security issues before presenting
the result to the user.

---

Environment Variables

The URL overrides are provided for enterprise deployments or development testing and should not be changed in normal usage.

---

Troubleshooting

"Not authenticated"

The MCP server requires a valid CODEPEEL_TOKEN environment variable.

1. Generate an API token from Settings → MCP Tokens.
2. Verify that your editor's MCP config contains "env": { "CODEPEEL_TOKEN": "cpk_..." }.
3. Restart your AI editor.

"No reviews remaining"

You have used all reviews for the current billing period. Options:

• Run check_credits to see your exact usage and reset date
• Wait for the monthly reset (1st of each month)
• Upgrade your plan for more reviews

See Billing for details on plans and quotas.

"Rate limit exceeded"

You have reached your plan's hourly rate limit. The error message includes the retry wait time. Rate limits apply per user across all review sources (MCP, VS Code extension, GitHub PRs). See Billing for plan details.

Server not starting

Run the server manually to see error output:

CODEPEEL_TOKEN=cpk_your-token npx -y @codepeelai/codepeel

Common causes:

• Node.js not installed or too old. The server requires Node.js 18 or later.
• Network issues. The server needs internet access to reach the CodePeel API.
• npx cache issues. Try clearing the npx cache: npx --yes @codepeelai/codepeel help

Server starts but tools do not appear

If the server starts successfully but your AI agent does not show the CodePeel tools:

1. Restart your AI editor after adding or modifying the MCP configuration
2. Verify the configuration file path is correct for your editor and operating system
3. Check your editor's MCP server logs for connection errors
4. Ensure the command field is "npx" (not "node" or a full path)
5. Try running npx -y @codepeelai/codepeel help to confirm the package resolves correctly

"diff is too short or empty"

The review_code tool requires a diff of at least 10 characters. This error occurs when:

• The git diff is empty (no changes to review)
• The diff string was not passed correctly to the tool
• The AI agent passed a file path instead of the actual diff content

Ensure your agent is running git diff and passing the output string, not the command itself.

Payment failed error

Your last subscription payment was declined. The MCP server blocks all review calls until the payment issue is resolved. Update your payment method at codepeel.com/app/billing.

---

Frequently Asked Questions

Does the MCP server store my code?

No. The MCP server is a thin client that forwards your diff to the CodePeel review API. The diff is processed by the AI analysis engine and is not stored permanently after the review completes. The server itself runs locally on your machine and does not persist any data between calls.

Can I use the MCP server in CI/CD pipelines?

Yes. Any CI/CD workflow or automated agent that supports MCP can run the CodePeel MCP server using your CODEPEEL_TOKEN. Alternatively, install the CodePeel GitHub App to automatically review every pull request on GitHub without any CI configuration required.

What is the difference between the MCP server and the VS Code extension?

The MCP server provides tools that AI agents call programmatically. The VS Code extension provides a visual interface with inline comments, diagnostics, and a sidebar. Both use the same backend review API and consume from the same quota.

Do I need both the MCP server and the VS Code extension?

No. They are independent and serve different workflows. Use the MCP server if you want your AI agent to self-review its code. Use the VS Code extension if you prefer a visual review experience. You can use both simultaneously -- they share the same quota but operate independently.

What languages does the review support?

The review engine analyzes any language that appears in a unified diff. It handles all major programming languages including TypeScript, JavaScript, Python, Go, Rust, Java, C#, Ruby, PHP, Swift, Kotlin, Dart, and more. Language detection is automatic based on file extensions in the diff headers.

How large can the diff be?

Diffs up to 500 KB are processed reliably. For larger changesets, consider reviewing in smaller batches by splitting the diff by file or directory.

---

Related Documentation

• Billing -- Plans, review quotas, and how reviews are consumed
• Configuration -- .codepeel.yml reference for custom rules and review settings
• VS Code Extension -- Visual code review interface with inline comments