> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perfai.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Perfai MCP

> Use Perfai security tools directly inside your AI coding assistant — Claude Code, Cursor, VS Code, Windsurf, Zed, or any MCP-compatible client.

The **Perfai MCP server** (`@perfai/mcp`) connects Perfai to your AI coding assistant via the [Model Context Protocol](https://modelcontextprotocol.io). 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.

<Note>
  **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.
</Note>

<CardGroup cols={2}>
  <Card title="Claude Code" icon="terminal" href="/docs/mcp/claude-code">
    One-command setup via the `claude mcp add` CLI.
  </Card>

  <Card title="Cursor" icon="arrow-pointer" href="/docs/mcp/cursor">
    Global or per-project config via `.cursor/mcp.json`.
  </Card>

  <Card title="VS Code (Copilot Agent Mode)" icon="code" href="/docs/mcp/vscode">
    Add to `.vscode/mcp.json` or user settings.
  </Card>

  <Card title="Windsurf" icon="wind" href="/docs/mcp/windsurf">
    Drop the config in `~/.codeium/windsurf/mcp_config.json`.
  </Card>

  <Card title="Zed" icon="bolt" href="/docs/mcp/zed">
    Register via `context_servers` in Zed's `settings.json`.
  </Card>

  <Card title="Generic MCP client" icon="plug" href="/docs/mcp/generic">
    Works with any client that supports stdio MCP servers.
  </Card>
</CardGroup>

***

## Requirements

* **Node.js 18 or later** — run `node --version` to check.
* A **Perfai account** — sign up at [cloud.perfai.ai](https://cloud.perfai.ai).

***

## The command

The Perfai MCP server is published as [`@perfai/mcp`](https://www.npmjs.com/package/@perfai/mcp). Launch it with `npx`, naming the `perfai-mcp-server` binary:

```bash theme={null}
npx --yes --package=@perfai/mcp@latest perfai-mcp-server
```

<Warning>
  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`.
</Warning>

In a JSON config file this becomes:

```json theme={null}
{
  "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`).

<Steps>
  <Step title="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](https://cloud.perfai.ai).
  </Step>

  <Step title="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.
  </Step>

  <Step title="Confirm you're authenticated">
    Ask **"What's my Perfai auth status?"** — once it reports authenticated, the protected tools become available.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

***

## 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                    |

<Note>
  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).
</Note>

***

## Typical workflow

<Steps>
  <Step title="Log in">
    `Login to Perfai`
  </Step>

  <Step title="Select an organization">
    `List my Perfai organizations` → `Select organization 1`
  </Step>

  <Step title="Select an app">
    `List my Perfai apps` → `Select the app payment-api`
  </Step>

  <Step title="Review issues">
    `Summarize all issues for this app`, then drill in: `Show critical and high security issues`
  </Step>

  <Step title="Generate fixes">
    By ID, by category, or across the board (see below).
  </Step>
</Steps>

***

## 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:

* [Claude Code](/docs/mcp/claude-code)
* [Cursor](/docs/mcp/cursor)
* [VS Code](/docs/mcp/vscode)
* [Windsurf](/docs/mcp/windsurf)
* [Zed](/docs/mcp/zed)
* [Generic MCP client](/docs/mcp/generic)