Generic MCP client

The Perfai MCP server works with any client that supports stdio MCP servers — Claude Desktop, JetBrains AI, Continue.dev, and others. This page covers the general configuration pattern and direct CLI usage.

How it runs

The server is distributed as the @perfai/mcp npm package and launched with npx:

npx --yes --package=@perfai/mcp@latest perfai-mcp-server

It communicates over stdio (stdin/stdout) — the standard MCP transport. Your client starts the server as a subprocess and exchanges messages over stdin/stdout.

You must name the perfai-mcp-server binary via --package=. Running npx @perfai/mcp alone fails with “could not determine executable to run” because the package’s binary does not match its name.

Authentication

The server signs in with your Perfai username and password, supplied as the PERFAI_USERNAME and PERFAI_PASSWORD environment variables in the server’s env block. After the login tool runs, the session is saved locally.

Credentials are stored in plaintext in the MCP config file. Keep that file private and out of shared repositories.

Standard config format

Most MCP clients use a JSON config with an mcpServers key:

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

Common config file locations by client:

Client	Config file
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`
Claude Desktop (Linux)	`~/.config/Claude/claude_desktop_config.json`
Continue.dev	`.continue/config.json` in your project
JetBrains AI	Via the MCP plugin settings in the IDE

VS Code uses "servers" instead of "mcpServers" at the top level. See the VS Code setup guide for details. Zed uses a nested "context_servers" object with env inside command. See the Zed setup guide.

Claude Desktop setup

macOS
Windows
Linux

File: ~/Library/Application Support/Claude/claude_desktop_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"
      }
    }
  }
}

File: %APPDATA%\Claude\claude_desktop_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"
      }
    }
  }
}

File: ~/.config/Claude/claude_desktop_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"
      }
    }
  }
}

Restart Claude Desktop after saving the config. The perfai-mcp server should appear in the MCP tools panel.

Requirements

Node.js 18+ — the server requires Node 18 or later. Run node --version to check.
npx must be on your system PATH. It comes bundled with Node.js.

Tools

Before login, only login and auth_status are available. After authenticating, your client gains access to:

Tool	Description
`login`	Signs in using `PERFAI_USERNAME` / `PERFAI_PASSWORD`
`auth_status`	Current authentication status
`user_info`	Authenticated user details
`logout`	Clear the saved session
`manage_organizations`	List and select an organization
`list_apps`	List apps (search, environment filter, pagination)
`select_app`	Select an app by number, name, or ID
`setup`	Set up organization and app with defaults
`summarize_issues`	Counts of security, design, and quality issues
`show_security_issues`	Security issues — filter by severity, status, sort
`show_design_issues`	Design issues — filter by status, sort
`show_quality_issues`	Quality/spec issues — filter by sort
`ai_fix_security_issue`	AI fix prompt for a security issue
`ai_fix_design_issue`	AI fix prompt for a design issue
`ai_fix_quality_issue`	AI fix prompt for a quality issue
`show_fixed_issues`	Issues AI-fixed in this session
`check_security_fixes` / `check_design_fixes` / `check_quality_fixes`	Verify previously fixed issues are resolved

The prompts below run inside your MCP client’s chat (Claude Desktop, JetBrains AI, Continue.dev, etc.), not your terminal. The only terminal/file steps are editing the config.

With your credentials set in the env block, tell your AI assistant:

Login to Perfai

The server reads the env vars, authenticates, and stores the session locally. Confirm with What's my Perfai auth status?.

Common prompts

List my Perfai organizations

List my Perfai apps and select payment-api

Summarize all issues for the selected app

Show critical and high security issues

Generate a fix for security issue 33

Generate fixes for all design issues

Troubleshooting

could not determine executable to run

You’re missing the binary name. Use npx --yes --package=@perfai/mcp@latest perfai-mcp-server, not npx @perfai/mcp.

Authentication Failed / Configuration Required

The server didn’t find credentials. Confirm PERFAI_USERNAME and PERFAI_PASSWORD are set in the server’s env block and restart the client.

Server not starting

Confirm node --version returns 18 or later.
Run npx --yes --package=@perfai/mcp@latest perfai-mcp-server in a terminal to test directly — startup messages and any errors appear in the output.

npx not found

Install Node.js from nodejs.org. npx is included automatically.
On macOS with Homebrew: brew install node.

Getting Started

Core Concepts

Hybrid Deployment

Changelog

How it runs

Authentication

Standard config format

Claude Desktop setup

Requirements

Tools

Common prompts

Troubleshooting

​How it runs

​Authentication

​Standard config format

​Claude Desktop setup

​Requirements

​Tools

​Login

​Common prompts

​Troubleshooting

How it runs

Authentication

Standard config format

Claude Desktop setup

Requirements

Tools

Login

Common prompts

Troubleshooting