Setting Up the CodePeel MCP Server with Claude Code

CodePeel ships as a local MCP (Model Context Protocol) server, published on npm as @codepeelai/codepeel. Once registered with an MCP client, it gives your coding agent four tools and three prompts: review a diff, generate a fix, ask questions about your code, and check your review balance. This walkthrough covers the setup with Claude Code specifically — registration, authentication, the tool surface, and what to do when something does not work.

The server speaks MCP over stdio: Claude Code spawns it as a child process, and every request your agent makes is routed to CodePeel's review backend. Nothing listens on your network except, briefly, a localhost callback during browser-based sign-in.

Prerequisites

• Node.js 18 or newer (the server is invoked through npx).
• A CodePeel account, and either an API token or a GitHub/CodePeel login for the OAuth flow.
• A git checkout to review — the tools operate on diffs you or the agent produce.

Create an API token in the dashboard under Settings → MCP Tokens if you prefer static credentials. Tokens start with cpk_ and should be treated like passwords: do not commit them, and rotate them if they ever appear in a diff (the security scan will tell you if one does — see How CodePeel's OWASP Security Scanning Works).

Registering the server with Claude Code

The fastest registration is one command:

# 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

That registers a stdio server named codepeel whose command is npx -y @codepeelai/codepeel, with the token injected as an environment variable. Under the hood it writes to Claude Code's MCP configuration, equivalent to:

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

Scope matters: registering at user scope makes CodePeel available in every project; project scope stores the config in the repository (convenient for teams, but then the token must come from each developer's environment rather than a committed file). After registering, restart Claude Code and run /mcp to confirm the server connects — you should see codepeel listed with its tools available.

The same configuration works for other stdio-capable clients: Cursor, Cline, Roo, Windsurf, Kiro, and Claude Desktop all accept the mcpServers shape above.

Authentication: static token or OAuth

The server accepts two authentication paths.

API token (recommended for automation)

Set CODEPEEL_TOKEN in the server's env block, as above. Every tool call carries the token to the CodePeel API. If the token is missing, invalid, or expired, tool calls fail with an explicit message telling you to create a new cpk_ token and update the env block — the server does not silently retry with bad credentials.

Browser-based OAuth

If you start the server without a token, it can sign you in through OAuth with PKCE when a tool is first used:

1. The server fetches the authorization server's metadata and registers itself as a dynamic client.
2. It generates a PKCE code verifier and S256 code challenge, plus a random state parameter.
3. It starts a temporary HTTP server on an ephemeral port bound to 127.0.0.1 and opens your browser at the authorization endpoint, requesting the mcp:read and mcp:write scopes.
4. After you approve, the provider redirects to http://127.0.0.1:<port>/callback. The server validates state, exchanges the authorization code (with the original verifier) for an access token, and shows a short "Authenticated — you can close this window" page.
5. The token is persisted locally with its expiry, so subsequent sessions reuse it until it expires.

Because the callback listener is bound to the loopback interface on a random port and lives only for the duration of sign-in, the flow works without any inbound firewall rules.

The tool surface

Four tools are exposed. Schemas are declared through MCP, so Claude Code knows how to call them without prompting.

A typical agentic loop looks like this: Claude Code stages its work, runs git diff --cached, sends the result to review_code, and gets back a structured findings list. For each finding it can pull the suggested fix into context, apply it, and re-review. Because review_code accepts any unified diff, the same flow works for uncommitted working-tree changes, a whole branch diff against main, or a diff an agent constructed from memory.

Requests use your plan's review allowance — the same quota as pull-request and editor reviews. The server performs a balance check before spending a review, and check_credits lets the agent (or you) inspect the balance without cost. For the deduction rules, see review usage and limits.

Prompts for common workflows

Alongside the tools, the server registers three MCP prompts — reusable instruction templates your client can invoke by name:

• review-staged-changes — reviews the current staged diff end to end.
• security-audit — focuses the review on security findings (the OWASP/CWE pass described in the security scanning article).
• explain-and-fix — pairs an explanation of each problem with a concrete fix.

In Claude Code, prompts surface through the client's prompt/slash interface, so review-staged-changes becomes a one-step way to hand the agent a complete, well-formed review instruction instead of improvising one.

Quotas, rate limits, and what errors mean

The server maps backend errors to actionable text rather than leaking stack traces:

• 401 — invalid or expired token. The message tells you to create a new cpk_ token at the API-tokens page and update your env block.
• 429 — rate limit exceeded, with a retry-after interval included so the agent can wait and retry instead of hammering.
• 402 — no reviews remaining. The message includes the tier quota (30/month on Free, 500/month on Pro) and the link to billing. Reviews reset at the start of your billing cycle.
• 503 — all providers temporarily at capacity; the correct behavior is to retry shortly.

Because these are returned as tool results (not crashes), the agent can incorporate them into its plan — for example, backing off after a 429 rather than declaring the review failed.

Troubleshooting

The server does not appear in /mcp. Confirm Node.js 18+ is installed and on PATH (node --version), confirm the command npx -y @codepeelai/codepeel runs on its own, then restart Claude Code. Stdio servers that fail to start silently simply never register.

Windows PowerShell returns error: unknown option '-y'. In PowerShell, unquoted -- is intercepted and stripped as an end-of-parameters delimiter before claude receives it. Wrap the delimiter in quotes: "--" (claude mcp add codepeel --env CODEPEEL_TOKEN=cpk_... "--" npx -y @codepeelai/codepeel).

Tools appear but every call fails with a token error. Check that CODEPEEL_TOKEN starts with cpk_ and has not been rotated. Remember that changing the token in your config requires a client restart so the server process is respawned with the new environment.

Review results look different from PR reviews. The MCP path receives only the diff (and repository name) you send it. It does not have the pull request's metadata, CI context, or conversation history. Scope the diff precisely — git diff main...HEAD usually gives a better review than the full working-tree diff — and see the VS Code walkthrough for a mode that assembles branch diffs for you.

OAuth window closes without authenticating. The loopback callback must reach the server process. Corporate tools that rewrite localhost traffic or aggressive cookie/browser profiles can interrupt the handoff; fall back to a cpk_ token, which requires no browser round-trip.

Why MCP is worth the setup

The MCP server moves review before the pull request: your agent self-reviews staged work, applies fixes, and only then opens the PR — so the human-facing review starts cleaner. It composes with the rest of the surface: the pre-merge quality gates still enforce standards on the pull request itself, and the auto-fix pipeline can batch the remaining fixable findings into a follow-up PR. For the reference configuration, see the MCP docs.