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

# Generic MCP client

> Use the Perfai MCP server with any client that supports stdio-based MCP servers.

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`](https://www.npmjs.com/package/@perfai/mcp) npm package and launched with `npx`:

```bash theme={null}
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.

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

***

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

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

***

## Standard config format

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

```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"
      }
    }
  }
}
```

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                            |

<Note>
  VS Code uses `"servers"` instead of `"mcpServers"` at the top level. See the [VS Code setup guide](/docs/mcp/vscode) for details.
  Zed uses a nested `"context_servers"` object with `env` inside `command`. See the [Zed setup guide](/docs/mcp/zed).
</Note>

***

## Claude Desktop setup

<Tabs>
  <Tab title="macOS">
    File: `~/Library/Application Support/Claude/claude_desktop_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"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windows">
    File: `%APPDATA%\Claude\claude_desktop_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"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Linux">
    File: `~/.config/Claude/claude_desktop_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"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

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          |

***

## Login

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

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](https://nodejs.org). `npx` is included automatically.
* On macOS with Homebrew: `brew install node`.