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

# VS Code (Copilot Agent Mode)

> Install and use the Perfai MCP server in VS Code with GitHub Copilot in Agent mode.

VS Code supports MCP servers through GitHub Copilot's **Agent mode** (available in VS Code 1.99+). The config uses a `servers` key (not `mcpServers`) and can be scoped globally or per-project.

<Note>
  MCP tool use requires **GitHub Copilot Chat** with **Agent mode** enabled. Make sure you're running VS Code 1.99 or later.
</Note>

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

***

## Global installation

The global MCP config is stored in VS Code's user data directory.

<Tabs>
  <Tab title="macOS">
    File: `~/Library/Application Support/Code/User/mcp.json`

    ```json theme={null}
    {
      "servers": {
        "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/Code/User/mcp.json`

    ```json theme={null}
    {
      "servers": {
        "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%\Code\User\mcp.json`

    ```json theme={null}
    {
      "servers": {
        "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>

<Warning>
  VS Code uses `"servers"` as the top-level key — **not** `"mcpServers"`. Using the wrong key means the server will not be discovered.
</Warning>

***

## Project-scoped installation

Add `.vscode/mcp.json` to your project root. VS Code picks this up automatically when the workspace opens.

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

<Warning>
  Don't commit `.vscode/mcp.json` if it contains your `PERFAI_PASSWORD`. Add it to `.gitignore`, or keep credentials in the global user config instead. VS Code also supports `${input:...}` variables to prompt for secrets rather than hardcoding them.
</Warning>

***

## Verify the server is running

1. Open the **Command Palette** (`Cmd+Shift+P` / `Ctrl+Shift+P`).
2. Run **"MCP: List Servers"** — confirm **perfai-mcp** appears and shows a running status.
3. If it's stopped, run **"MCP: Restart Server"** and select **perfai-mcp**.

***

## Login

<Note>
  The prompts below run **inside Copilot Chat (Agent mode)**, not your terminal. The only terminal/file steps are editing the config.
</Note>

Open Copilot Chat, switch to **Agent mode**, and 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 "mobile-backend"
```

***

## 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 12
```

**By category:**

```
Generate fixes for all design issues
```

**For all / by severity** — ask Copilot to iterate:

```
List all critical security issues, then generate a fix for each one
```