Claude Code

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.

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.

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.

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.

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

Manual configuration

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

macOS / Linux
Windows

Global (all projects) — file: ~/.claude.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"
      }
    }
  }
}

Project scope — file: .mcp.json in 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"
      }
    }
  }
}

Global (all projects) — file: %USERPROFILE%\.claude.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"
      }
    }
  }
}

Project scope — file: .mcp.json in 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"
      }
    }
  }
}

Verify the server is connected

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

claude mcp list

The prompts below run inside the Claude Code chat, not your terminal. The only terminal steps are the install command and claude mcp list.

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`

Getting Started

Core Concepts

Hybrid Deployment

Changelog

Install with one command

Manual configuration

Verify the server is connected

Select an organization and app

List issues

Generate fixes

Useful prompts

​Install with one command

​Manual configuration

​Verify the server is connected

​Login

​Select an organization and app

​List issues

​Generate fixes

​Useful prompts

Install with one command

Manual configuration

Verify the server is connected

Login

Select an organization and app

List issues

Generate fixes

Useful prompts