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-cloud-mcp npm package and launched with npx:

npx -y perfai-cloud-mcp

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

Authentication

By default, the login tool opens a browser to Perfai’s own sign-in page (OAuth) and completes the session automatically — no credentials in your config required. To skip the browser — for example on a headless machine or in CI — create a Perfai API key and add it to the server’s env block as PERFAI_API_KEY:

{
  "mcpServers": {
    "perfai-cloud-mcp": {
      "command": "npx",
      "args": ["-y", "perfai-cloud-mcp"],
      "env": { "PERFAI_API_KEY": "pfk_xxxxxxxxxxxx_..." }
    }
  }
}

PERFAI_TOKEN also accepts an API key.

Keep any config file that holds an API key private, and out of shared repositories.

Standard config format

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

{
  "mcpServers": {
    "perfai-cloud-mcp": {
      "command": "npx",
      "args": ["-y", "perfai-cloud-mcp"]
    }
  }
}

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 a command object (path/args) inside it. See the Zed setup guide.

Claude Desktop setup

macOS
Windows
Linux

File: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "perfai-cloud-mcp": {
      "command": "npx",
      "args": ["-y", "perfai-cloud-mcp"]
    }
  }
}

File: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "perfai-cloud-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "perfai-cloud-mcp"]
    }
  }
}

Windows needs the cmd /c wrapper because npx is a .cmd shim, not a real executable — without it Claude Desktop’s logs will show spawn npx ENOENT and the server disconnects immediately.

File: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "perfai-cloud-mcp": {
      "command": "npx",
      "args": ["-y", "perfai-cloud-mcp"]
    }
  }
}

Fully quit and reopen Claude Desktop after saving the config (closing the window alone leaves the old process running with the stale config). The perfai-cloud-mcp server should then appear in Settings → Developer → Local MCP servers.

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:

Authentication

Tool	Description
`login`	Sign in to Perfai — opens a browser, or uses `PERFAI_API_KEY` if set
`auth_status`	Current authentication status
`logout`	Clear the saved session

Organization management

Tool	Description
`manage_organizations`	List the organizations your account belongs to and switch between them

App management

Tool	Description
`register_app`	Register a new app by URL for security testing
`check_app_status`	Poll registration progress until complete
`list_apps`	List all your registered apps
`select_app`	Switch to a different registered app
`submit_app_credentials`	Provide login credentials for apps that require authentication

Security testing

Tool	Description
`run_security_test`	Start a security scan on the current app
`check_task_status`	Poll scan progress until complete

Vulnerability management

Tool	Description
`get_vulnerabilities`	List all findings from the latest scan
`suggest_fix`	Conversational fix prompt for a specific vulnerability
`auto_fix`	Structured, step-by-step fix instructions for one vulnerability
`auto_fix_all`	Prioritized fix plan for all unfixed vulnerabilities
`get_fix_summary`	Fix progress — fixed/unfixed/dismissed by severity
`dismiss_vulnerability`	Dismiss a finding (false positive, accepted risk, etc.)
`reopen_vulnerability`	Reopen a previously dismissed finding
`mark_vulnerability_fixed`	Mark a finding as fixed after applying the code change

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.

Tell your AI assistant:

Login to Perfai

This opens a browser to Perfai’s sign-in page (or uses PERFAI_API_KEY if you set it). Confirm with What's my Perfai auth status?.

Common prompts

Register https://myapp.com with Perfai

Run a security test on the selected app

Show me all vulnerabilities for this app

Auto-fix all critical and high vulnerabilities

Mark vulnerability 3 as fixed

Give me the fix summary

Troubleshooting

Server disconnects immediately / spawn npx ENOENT

On Windows, wrap the command through cmd: "command": "cmd", "args": ["/c", "npx", "-y", "perfai-cloud-mcp"].

MCP error -32000: Connection closed or a crash naming a missing file inside node_modules (e.g. axios/lib/adapters/...)

This is usually a corrupted or partially-extracted npx cache, often caused by the client spawning the server twice in quick succession. Clear the cache entry under ~/.npm/_npx/ (macOS/Linux) or %LOCALAPPDATA%\npm-cache\_npx\ (Windows), or avoid the issue entirely by installing once (npm install -g perfai-cloud-mcp) and pointing your config at perfai-cloud-mcp directly instead of npx.

“Authentication required” on every tool

Call login first. If you’re relying on the browser flow, make sure the popup wasn’t blocked.

No tools visible after connecting

Fully restart your client (not just close the window) so it re-reads the config, then check the client’s MCP server logs for the actual error.

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

Authentication

Organization management

App management

Security testing

Vulnerability management

Common prompts

Troubleshooting

​How it runs

​Authentication

​Standard config format

​Claude Desktop setup

​Requirements

​Tools

​Authentication

​Organization management

​App management

​Security testing

​Vulnerability management

​Login

​Common prompts

​Troubleshooting

How it runs

Authentication

Standard config format

Claude Desktop setup

Requirements

Tools

Authentication

Organization management

App management

Security testing

Vulnerability management

Login

Common prompts

Troubleshooting