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

# Windsurf

> Install and use the Perfai MCP server in Windsurf — globally or scoped to a project.

Windsurf (by Codeium) supports MCP servers via a JSON config file. Register Perfai globally so it's available across all workspaces, or add it per-project.

<Warning>
  The package binary is `perfai-mcp-server`. Always launch it with `npx --yes --package=@perfai/mcp@latest perfai-mcp-server` — `npx @perfai/mcp` alone fails with *"could not determine executable to run."*
</Warning>

<Note>
  Authentication uses your Perfai username and password via the `PERFAI_USERNAME` / `PERFAI_PASSWORD` environment variables. Because these sit in plaintext, prefer global config and don't commit credentials to a shared repo.
</Note>

***

## Global installation

<Tabs>
  <Tab title="macOS / Linux">
    File: `~/.codeium/windsurf/mcp_config.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"
          }
        }
      }
    }
    ```

    Create the file if it doesn't exist:

    ```bash theme={null}
    mkdir -p ~/.codeium/windsurf
    touch ~/.codeium/windsurf/mcp_config.json
    ```
  </Tab>

  <Tab title="Windows">
    File: `%USERPROFILE%\.codeium\windsurf\mcp_config.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"
          }
        }
      }
    }
    ```

    Create the file if it doesn't exist (run in PowerShell):

    ```powershell theme={null}
    New-Item -Path "$env:USERPROFILE\.codeium\windsurf\mcp_config.json" -Force
    ```
  </Tab>
</Tabs>

***

## Project-scoped installation

Add `.windsurf/mcp.json` to 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"
      }
    }
  }
}
```

<Warning>
  Don't commit `.windsurf/mcp.json` if it contains your `PERFAI_PASSWORD` — add it to `.gitignore`, or keep credentials in the global config instead.
</Warning>

***

## Enable the server in Windsurf

After saving the config:

1. Open **Windsurf Settings** → **MCP Servers**.
2. Confirm **perfai-mcp** appears and shows a connected status.
3. If it shows as disconnected, click **Restart**.

Alternatively, use the Windsurf command palette and search for **"MCP: Refresh Servers"**.

***

## Login

<Note>
  The prompts below run **inside the Windsurf Cascade chat**, not your terminal. The only terminal/file steps are creating the config file.
</Note>

In the Windsurf AI panel (Cascade), type:

```
Login to Perfai
```

The server reads `PERFAI_USERNAME` / `PERFAI_PASSWORD` from the config, signs you in, and saves the session locally. 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 "checkout-service"
```

***

## List issues

Findings are grouped into **security**, **design**, and **quality** categories.

```
Summarize all issues for the selected app
```

```
Show critical and high security issues
```

```
Show all design issues
```

```
Show quality issues
```

***

## Generate fixes

**By ID** (sequence number, issue ID, or description):

```
Generate a fix for security issue 8
```

**By category:**

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

**For all / by severity** — ask Cascade to iterate:

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