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

# Claude Code

> Install and use the Perfai MCP server in Claude Code with a single CLI command.

## Install with one command

The fastest way to add Perfai to Claude Code is via the `claude mcp add` command. This registers the MCP server globally — it will be available in every project automatically.

```bash theme={null}
claude mcp add perfai-mcp --scope user \
  -e PERFAI_USERNAME=you@example.com \
  -e PERFAI_PASSWORD=your-password \
  -- npx --yes --package=@perfai/mcp@latest perfai-mcp-server
```

Restart Claude Code (or open a new session) and the Perfai tools are ready.

<Warning>
  Authentication uses your Perfai username and password, passed as the `PERFAI_USERNAME` and `PERFAI_PASSWORD` environment variables. They are stored in plaintext in `~/.claude.json` — keep it private and prefer user scope over project scope for anything with credentials.
</Warning>

<Warning>
  Use the **long-form** npx flags (`--yes --package=…`). The short `-y`/`-p` flags after `--` are misread by the `claude mcp add` parser, and `npx @perfai/mcp` without an explicit binary fails with *"could not determine executable to run"* — the binary is named `perfai-mcp-server`.
</Warning>

<Note>
  `--scope user` registers the server globally. To limit it to a single project, use `--scope project` instead — this writes to `.mcp.json` in your current directory.
</Note>

***

## Manual configuration

If you prefer to edit the config file directly, add the following for your OS and scope.

<Tabs>
  <Tab title="macOS / Linux">
    **Global (all projects)** — file: `~/.claude.json`

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

    **Project scope** — file: `.mcp.json` in your project root

    ```json theme={null}
    {
      "mcpServers": {
        "perfai-mcp": {
          "command": "npx",
          "args": ["--yes", "--package=@perfai/mcp@latest", "perfai-mcp-server"],
          "env": {
            "PERFAI_USERNAME": "you@example.com",
            "PERFAI_PASSWORD": "your-password"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windows">
    **Global (all projects)** — file: `%USERPROFILE%\.claude.json`

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

    **Project scope** — file: `.mcp.json` in your project root

    ```json theme={null}
    {
      "mcpServers": {
        "perfai-mcp": {
          "command": "npx",
          "args": ["--yes", "--package=@perfai/mcp@latest", "perfai-mcp-server"],
          "env": {
            "PERFAI_USERNAME": "you@example.com",
            "PERFAI_PASSWORD": "your-password"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

***

## Verify the server is connected

List active MCP servers and confirm `perfai-mcp` shows **✔ Connected**:

```bash theme={null}
claude mcp list
```

***

## Login

<Note>
  The prompts below run **inside the Claude Code chat**, not your terminal. The only terminal steps are the install command and `claude mcp list`.
</Note>

With your credentials set in the `env` block above, authenticate:

```
Login to Perfai
```

The server reads `PERFAI_USERNAME` / `PERFAI_PASSWORD` from the environment, signs you in, and saves the session. Confirm with:

```
What's my Perfai auth status?
```

***

## Select an organization and app

```
List my Perfai organizations
```

```
Select organization 1
```

```
List my Perfai apps
```

```
Select the app called "payment-api"
```

***

## List issues

Perfai groups findings into three categories — **security**, **design**, and **quality**.

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

***

## Generate fixes

**By ID** — use the sequence number from the issue list, an issue ID, or a description:

```
Generate a fix for security issue 14
```

**By category:**

```
Generate fixes for all design issues
```

**For all (or by severity)** — ask Claude to iterate over a filtered list:

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

Then confirm the fixes landed:

```
Check which security fixes were actually resolved
```

***

## Useful prompts

| Goal                         | Prompt                                     |
| ---------------------------- | ------------------------------------------ |
| See your posture at a glance | `Summarize all Perfai issues for this app` |
| Check login status           | `What's my Perfai auth status?`            |
| Filter by severity           | `Show all critical security issues`        |
| Fix a specific issue         | `Generate a fix for security issue 17`     |
| Fix a whole category         | `Generate fixes for all quality issues`    |