Perfai MCP

The Perfai MCP server (@perfai/mcp) connects Perfai to your AI coding assistant via the Model Context Protocol. Once installed, you can list security, design, and quality issues, filter them by severity or status, and generate AI-powered fix prompts — all without leaving your editor.

Where to run Perfai commands: every Perfai action — Login to Perfai, Show critical security issues, Generate a fix for security issue 14, and so on — is a natural-language prompt you type into your code agent’s chat (Claude Code, Cursor, VS Code Copilot Agent Mode, Windsurf, or Zed). They are not terminal commands. Only the one-time installation steps (npx, claude mcp add, editing a config file) run in a shell.

Claude Code

One-command setup via the claude mcp add CLI.

Cursor

Global or per-project config via .cursor/mcp.json.

VS Code (Copilot Agent Mode)

Add to .vscode/mcp.json or user settings.

Windsurf

Drop the config in ~/.codeium/windsurf/mcp_config.json.

Zed

Generic MCP client

Works with any client that supports stdio MCP servers.

Requirements

Node.js 18 or later — run node --version to check.
A Perfai account — sign up at cloud.perfai.ai.

The command

The Perfai MCP server is published as @perfai/mcp. Launch it with npx, naming the perfai-mcp-server binary:

npx --yes --package=@perfai/mcp@latest perfai-mcp-server

The package binary is perfai-mcp-server — it does not share the package name, so npx @perfai/mcp alone fails with “could not determine executable to run.” Always pass --package=@perfai/mcp@latest perfai-mcp-server.

In a JSON config file this becomes:

{
  "command": "npx",
  "args": ["--yes", "--package=@perfai/mcp@latest", "perfai-mcp-server"],
  "env": {
    "PERFAI_USERNAME": "you@example.com",
    "PERFAI_PASSWORD": "your-password"
  }
}

How authentication works

The Perfai MCP server authenticates with your Perfai username and password, supplied as environment variables in the MCP config (PERFAI_USERNAME and PERFAI_PASSWORD).

Add your credentials

Set PERFAI_USERNAME and PERFAI_PASSWORD in the server’s env block (see your editor’s setup page). Use the same email and password you use at cloud.perfai.ai.

Run the login tool

Ask your AI assistant: “Login to Perfai”. The server reads your credentials from the environment, authenticates, and saves the session locally.

Confirm you're authenticated

Ask “What’s my Perfai auth status?” — once it reports authenticated, the protected tools become available.

Select an organization and app

Pick your organization, then select the app you want to work with. All issue and fix tools operate on the selected app.

Credentials are stored in plaintext in the MCP config file. Treat that file like a secret — don’t commit it to a shared repository. Prefer user-scoped (global) config over project-scoped config for anything containing credentials.

Tools

Only login and auth_status are available before you authenticate. After login, all of the following become available:

Tool	What it does
`login`	Authenticates using the `PERFAI_USERNAME` / `PERFAI_PASSWORD` env vars
`auth_status`	Shows current authentication status
`user_info`	Details about the authenticated user
`logout`	Clears your saved session
`manage_organizations`	Lists organizations and selects one
`list_apps`	Lists apps (search, environment filter, pagination)
`select_app`	Selects an app by number, name/label, or app ID
`setup`	Sets up organization and app with default values
`summarize_issues`	Summary of security, design, and quality issue counts for the selected app
`show_security_issues`	Lists security issues — filter by severity, status, sort
`show_design_issues`	Lists design issues — filter by status, sort
`show_quality_issues`	Lists quality/spec issues — filter by sort
`ai_fix_security_issue`	Generates an AI fix prompt for a security issue
`ai_fix_design_issue`	Generates an AI fix prompt for a design issue
`ai_fix_quality_issue`	Generates an AI fix prompt for a quality issue
`show_fixed_issues`	Shows issues AI-fixed in the current session
`check_security_fixes` / `check_design_fixes` / `check_quality_fixes`	Re-checks whether previously fixed issues were resolved

Perfai groups findings into three categories: security, design, and quality. Each has its own list and fix tool. Within security, you can further filter by severity (Critical, High, Medium, Low).

Typical workflow

Login to Perfai

Select an organization

List my Perfai organizations → Select organization 1

Select an app

List my Perfai apps → Select the app payment-api

Review issues

Summarize all issues for this app, then drill in: Show critical and high security issues

Generate fixes

By ID, by category, or across the board (see below).

Listing issues

Summarize all issues for the selected app

Show critical and high security issues

Show open security issues sorted by CVSS

Show all design issues

Show quality issues

Generating fixes

By ID (sequence number from the issue list, an issue ID, or a description):

Generate a fix for security issue 14

By category (security, design, or quality):

Generate fixes for all design issues

For all / by severity — ask your assistant to iterate over a filtered list:

List all critical security issues, then generate a fix for each one

After applying fixes, confirm they resolved:

Check which security fixes were actually resolved

Next steps

Pick your editor to get started:

Getting Started

Core Concepts

Hybrid Deployment

Changelog

Claude Code

Cursor

VS Code (Copilot Agent Mode)

Windsurf

Zed

Generic MCP client

Requirements

The command

How authentication works

Tools

Typical workflow

Listing issues

Generating fixes

Next steps

Claude Code

Cursor

VS Code (Copilot Agent Mode)

Windsurf

Zed

Generic MCP client

​Requirements

​The command

​How authentication works

​Tools

​Typical workflow

​Listing issues

​Generating fixes

​Next steps

Requirements

The command

How authentication works

Tools

Typical workflow

Listing issues

Generating fixes

Next steps