Windsurf

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.

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

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.

Global installation

macOS / Linux
Windows

File: ~/.codeium/windsurf/mcp_config.json

{
  "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:

mkdir -p ~/.codeium/windsurf
touch ~/.codeium/windsurf/mcp_config.json

File: %USERPROFILE%\.codeium\windsurf\mcp_config.json

{
  "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):

New-Item -Path "$env:USERPROFILE\.codeium\windsurf\mcp_config.json" -Force

Project-scoped installation

Add .windsurf/mcp.json to your project root:

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

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

Enable the server in Windsurf

After saving the config:

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

Alternatively, use the Windsurf command palette and search for “MCP: Refresh Servers”.

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

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

Getting Started

Core Concepts

Hybrid Deployment

Changelog

Global installation

Project-scoped installation

Enable the server in Windsurf

Select an organization and app

List issues

Generate fixes

​Global installation

​Project-scoped installation

​Enable the server in Windsurf

​Login

​Select an organization and app

​List issues

​Generate fixes

Global installation

Project-scoped installation

Enable the server in Windsurf

Login

Select an organization and app

List issues

Generate fixes