MCP Server

The CodePeel MCP server exposes AI code review as a set of tools 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 Code, Augment, Windsurf, Codex, Goose, Zed, and any client that implements the Model Context Protocol.

---

Prerequisites

Before setting up the MCP server, you need a CodePeel account and an API token.

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.

Create an API token

API tokens are persistent credentials that authenticate the MCP server with the CodePeel backend. Unlike Firebase session tokens (which expire after 1 hour), API tokens do not expire unless you set an explicit expiration date or manually revoke them.

1. Go to Settings in the sidebar
2. Navigate to the API Tokens tab
3. Click Create new token
4. Give it a name (e.g., "Cursor MCP" or "Claude Code")
5. Optionally set an expiration (7, 30, 60, 90, or 365 days -- or never)
6. Copy the token immediately -- it starts with cpk_ and will not be shown again

Store the token securely. You can create multiple tokens for different editors or machines, and revoke any token individually from the Settings page without affecting others.

---

Setup

The MCP server is distributed via GitHub 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.

Manual Configuration

Add the CodePeel server to your editor's MCP configuration file. The configuration is the same across all editors — only the file path differs.

Kiro

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

{
  "mcpServers": {
    "codepeel": {
      "command": "npx",
      "args": ["-y", "github:codepeel/mcp-server"],
      "env": {
        "CODEPEEL_TOKEN": "cpk_your-token-here"
      }
    }
  }
}

Claude Code (CLI)

Use the claude mcp add command:

claude mcp add codepeel --env CODEPEEL_TOKEN=cpk_your-token-here -- npx -y github:codepeel/mcp-server

Or add to the Claude Desktop configuration file:

• 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", "github:codepeel/mcp-server"],
      "env": {
        "CODEPEEL_TOKEN": "cpk_your-token-here"
      }
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "codepeel": {
      "command": "npx",
      "args": ["-y", "github:codepeel/mcp-server"],
      "env": {
        "CODEPEEL_TOKEN": "cpk_your-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 github:codepeel/mcp-server
   • Environment: CODEPEEL_TOKEN=cpk_your-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

The paths above are for Linux. On macOS, replace ~/.config/Code with ~/Library/Application Support/Code. On Windows, replace with %APPDATA%\Code.

npm (alternative)

If you prefer installing from the npm registry:

{
  "mcpServers": {
    "codepeel": {
      "command": "npx",
      "args": ["@codepeel/mcp-server"],
      "env": {
        "CODEPEEL_TOKEN": "cpk_your-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 multi-layer analysis engine 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 table with your plan tier, reviews used, reviews remaining (or "Unlimited" for Max), reset date, and account name. Includes a warning if your balance is low or exhausted.

Example output:

## CodePeel Account

| | |
|---|---|
| **Plan** | Pro |
| **Used** | 127 / 500 reviews |
| **Remaining** | 373 reviews |
| **Resets** | 7/1/2026 |
| **Account** | @yourname |

---

How It Works

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

Architecture

The server operates as a stdio-based MCP process. When your AI editor starts the server, it launches npx @codepeel/mcp-server as a child process and communicates over stdin/stdout using the MCP JSON-RPC protocol. The server registers its tools on startup and handles tool calls as they arrive.

Request flow

1. Your AI agent decides to call a CodePeel tool (e.g., review_code)
2. The editor sends a CallToolRequest to the MCP server over stdio
3. The server reads the CODEPEEL_TOKEN environment variable for authentication
4. For review_code, fix_code, and ask_codepeel, the server first checks your credit balance via the /ide/credits/balance endpoint
5. If credits are available, the server makes the actual API call to the appropriate backend endpoint
6. The response is formatted as Markdown and returned to the agent as a ToolResult

Backend endpoints

The MCP server communicates with two backend services:

The review endpoint uses Google Cloud Run with a 540-second timeout to handle large diffs. All other endpoints use the standard Vercel-hosted API with a 30-second timeout.

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 skip the credit check entirely since they have unlimited reviews.

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 monthly quota. The check_credits tool is always free. All MCP tool calls draw from the same monthly pool as GitHub PR reviews and VS Code extension reviews. See Billing for full details on plans and quotas.

Rate limits

The same hourly rate limits apply to MCP calls as to all other review sources (Free: 3/hour, Pro: 6/hour, Max: 12/hour). Additionally, all API endpoints enforce a burst limit of 20 requests per minute per user. See Billing for 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
    using Promise.all and a single database 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.

---

CLI Commands

The @codepeel/mcp-server package doubles as a standalone CLI tool. When invoked with a command argument, it runs the specified command instead of starting the MCP server.

Command reference

Review from the terminal

Pipe any diff into the review command for instant feedback without an AI agent:

# Review all uncommitted changes
git diff | npx @codepeel/mcp-server review

# Review only staged changes (pre-commit)
git diff --cached | npx @codepeel/mcp-server review

# Review a patch file
cat changes.patch | npx @codepeel/mcp-server review

The command reads the diff from stdin, sends it to the review API, and prints the formatted results to stdout. If the diff is empty, it exits with a success message. If the token is missing or invalid, it prints an error to stderr and exits with code 1.

Check your balance

npx @codepeel/mcp-server credits

Prints your plan tier, reviews used, reviews remaining, and reset date. Useful for scripting or quick checks before running a batch of reviews.

Generate configuration

npx @codepeel/mcp-server init-config

Creates a .codepeel.yml file in the current directory based on your dashboard settings (ignored paths, custom instructions, strict mode, etc.). This file is read by both the VS Code extension and GitHub PR reviews. If a .codepeel.yml already exists, the command exits with a warning to prevent accidental overwrites.

See the Configuration documentation for the full .codepeel.yml reference.

Interactive setup

npx @codepeel/mcp-server init

Launches an interactive wizard that:

1. Asks which editor you are using (Kiro, Claude Code, Cursor, Cline, Roo)
2. Optionally opens your browser to the API token creation page
3. Prompts you to paste your cpk_ token
4. Writes the MCP configuration file for your selected editor
5. Confirms success and lists the available tools

---

Environment Variables

The CODEPEEL_TOKEN variable is the only required configuration. The URL overrides are provided for enterprise deployments or development testing and should not be changed in normal usage.

---

API Token Management

API tokens are the recommended authentication method for the MCP server. They provide persistent access without the 1-hour expiration of Firebase session tokens.

Token format

All API tokens start with the prefix cpk_ followed by 64 hexadecimal characters (32 random bytes). The prefix makes tokens easy to identify and prevents confusion with other credential types.

Example: cpk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Token lifecycle

• Creation: Tokens are generated via the Settings page or the /api/tokens endpoint. The full token value is shown exactly once at creation time.
• Validation: On each API call, the token is looked up in a global Firestore collection. The lastUsedAt timestamp is updated asynchronously.
• Expiration: Tokens can be created with an optional expiration (7, 30, 60, 90, or 365 days) or set to never expire. Expired tokens return a 401 with the TOKEN_EXPIRED error code.
• Revocation: Tokens can be revoked from the Settings page at any time. Revoked tokens are immediately invalid.

Best practices

• Create separate tokens for each editor or machine
• Use descriptive names (e.g., "Cursor - Work Laptop", "Claude Code - CI")
• Set expiration dates for tokens used in shared environments
• Revoke tokens immediately if compromised
• Never commit tokens to version control -- use environment variables or secrets managers

---

Troubleshooting

"CODEPEEL_TOKEN not set"

The environment variable is not reaching the MCP server process. Verify your configuration file includes the env block:

{
  "env": {
    "CODEPEEL_TOKEN": "cpk_your-token-here"
  }
}

If using Claude Code CLI, ensure the --env flag is correct:

claude mcp add codepeel --env CODEPEEL_TOKEN=cpk_your-token-here -- npx @codepeel/mcp-server

"Token expired" or "Invalid token"

This error has two common causes:

1. Using a Firebase session token instead of an API token. Firebase tokens expire after 1 hour. Always use a cpk_ token from Settings > API Tokens.

2. Token was revoked or has expired. Check your token list at Settings > API Tokens. Create a new token if needed.

To verify your token works, run:

CODEPEEL_TOKEN=cpk_your-token npx @codepeel/mcp-server credits

"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 hit either the hourly plan limit or the burst limit (20 requests/minute). The error message includes the wait time in seconds. Rate limits apply per user across all review sources (MCP, VS Code extension, GitHub PRs).

See rate limits for per-plan limits.

Server not starting

Run the server manually to see error output:

CODEPEEL_TOKEN=cpk_your-token npx @codepeel/mcp-server

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 @codepeel/mcp-server

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 @codepeel/mcp-server 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. The CLI commands (review and credits) work in any environment with Node.js 18+ and a CODEPEEL_TOKEN environment variable. Pipe your diff into the review command:

git diff origin/main...HEAD | CODEPEEL_TOKEN=$CODEPEEL_TOKEN npx @codepeel/mcp-server review

The exit code is 0 for success and 1 for errors, making it suitable for CI gates.

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 monthly 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?

There is no hard limit enforced by the MCP server itself, but the review API has practical limits. Diffs up to 500 KB are processed reliably. Very large diffs may time out (the review endpoint has a 540-second timeout). For large 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