Getting Started

Codacy Guardrails is a brand new way of enforcing code security and quality standards for AI-generated code, built into the free Codacy IDE Extension for VSCode, Copilot, Cursor, and Windsurf. Guardrails help developers ship safer, cleaner AI code by applying best practices and blocking insecure patterns while the code is being generated.

Besides real-time AI code scanning, Guardrails users can now prompt all their Codacy findings, without ever leaving the AI chat panel inside their IDE.

New to Codacy Guardrails? Check our blog post

VSCode-based IDEs

Prerequisites

• git
• node.js - ensure the npx command runs without issues
• curl

Supported Operating Systems

• macOS
• Linux
• Windows (via WSL)

Important

For Windows users: Windows WSL (a feature that allows you to run a Linux environment directly on Windows, without the need for a virtual machine or dual-boot setup) is the only way you can use this feature for now, but we're still working to fully support Windows. We currently only support VSCode, Cursor, and Windsurf on Windows.

Supported IDEs

• Visual Studio Code
• Cursor
• Windsurf

Note

For Visual Studio Code, the Insiders version is recommended for its faster performance and compatibility with Codacy Guardrails. However, since it's a beta version, you may encounter occasional issues.

Built-in Scanners

• Trivy
• Semgrep
• ESLint
• Pylint
• PMD
• dartanalyzer
• Lizard
• Revive

How to install - Quick Guide

Note for Windows users:

To take advantage of Codacy Guardrails on Windows, you might need to setup WSL first, check the steps here.

1. Download the extension

• Visual Studio Code
• Cursor
• Windsurf
• IntelliJ IDEA

This will open the Codacy Extension in your IDE Marketplace. Click Install

2. Install and activate the Codacy CLI for local analysis

Click on the button Install Codacy CLI

It will create a folder in your local repository called .codacy with all needed configuration:

• The configuration from all built-in scanners
• Codacy CLI script to run analysis locally

Note

If you don't want this folder to be part of your repository in future commits but continue working with it locally, please add .codacy to your .gitignore file

Note

The IDE extension will ignore any CLI version already installed (e.g. through brew or other package manager) on the machine.

3. Install MCP Server

a. Add the Codacy MCP Server

In the Codacy Extension tab, click Add Codacy MCP Server

b. Check if the Codacy MCP Server is enabled

On the left side menu of the Codacy extension, please make sure that MCP server is set up and ready.

4. Restart your IDE

5. After everything is set up, you should now be able to interact with Codacy via AI chat.

• Remember that for you to be able to interact with Codacy MCP server, you must be on the Agent mode of the chat, not the default Ask mode.
• If you're still having issues with the MCP server, try to run the command Preferences: Open User Settings (JSON), look for the Codacy MCP server settings and right on top of it you'll should see a Start option. Click on it and, if unsuccessful, go to View > Debug Console and check for errors. Don't forget to ensure you have node.js and npx installed and set up.

How to install - WSL

1. Install or update WSL.

2. Install curl on your WSL instance if it's not installed already.

• This will depend on the Linux distribution you are using, but for example in Debian and Ubuntu the command will be something like sudo apt update && sudo apt install curl. Execute the command on a WSL terminal.

3. Now you should be able to install the Codacy extension without issues. Go through the steps here.

How to install - Manually

1. Install and activate the Codacy CLI for local analysis

Download

MacOS (brew)

To install codacy-cli using Homebrew:

brew install codacy/codacy-cli-v2/codacy-cli-v2

Linux

For Linux, we rely on the codacy-cli.sh script in the root. To download the CLI, run:

bash <(curl -Ls https://raw.githubusercontent.com/codacy/codacy-cli-v2/main/codacy-cli.sh)

You can either put the downloaded script in a specific file or create an alias that will download the script and look for changes:

alias codacy-cli="bash <(curl -Ls https://raw.githubusercontent.com/codacy/codacy-cli-v2/main/codacy-cli.sh)"

Installation

Before running the analysis, install the specified tools:

codacy-cli install

2. Install MCP Server

If you want to use MCP Server with a NPM package you should download it from here

Important

You can find some limitations using this approach because the AI doesn't automatically analyse the code generated unless there's a rule set for it to do so. When using the IDE extension (VS Code, Cursor, or Windsurf), we create those AI rules for the workspace, but if you are installing the MCP manually, you will need to create those rules by yourself. Let us know if you you plan to use this approach, so we can provide more information

Setup

Cursor, Windsurf and Claude Desktop

Depending on what IDE you are connecting the MCP Server to, you can use the following methods:

• Cursor: edit the .cursor/mcp.json file to add the following
• Windsurf: edit the .codeium/windsurf/mcp_config.json file to add the following
• Claude Desktop: edit the claude_desktop_config.json file to add the following

{
  "mcpServers": {
    "codacy": {
      "command": "npx",
      "args": ["-y", "@codacy/codacy-mcp"],
      "env": {
        "CODACY_ACCOUNT_TOKEN": "<YOUR_TOKEN>",
        "CODACY_CLI_VERSION": "<VERSION>"
      }
    }
  }
}

VS Code with Copilot

For connecting the MCP Server to Copilot in VS Code, add the following to the global config of the IDE:

{
  "mcp": {
    "inputs": [],
    "servers": {
      "codacy": {
        "command": "npx",
        "args": ["-y", "@codacy/codacy-mcp"],
        "env": {
          "CODACY_ACCOUNT_TOKEN": "<YOUR_TOKEN>",
          "CODACY_CLI_VERSION": "<VERSION>"
        }
      }
    }
  }
}

You can open the user settings.json file in:

View > Command Palette > Preferences: Open User Settings (JSON)

Or open the general settings.json file directly, which according to your OS should be located in:

• for macOS: ~/Library/Application Support/Code/User/settings.json
• for Windows: %APPDATA%\Code\User\settings.json
• for Linux: ~/.config/Code/User/settings.json

Make sure you update the value of CODACY_ACCOUNT_TOKEN with your API token.

a. Above the MCP Server configuration in Settings.json file, you can Click in the command Start

b. Make sure you have Agent mode enabled: vscode://settings/chat.agent.enabled

c. Open the Copilot chat and switch the mode to Agent. You can check that the MCP server was enabled correctly by clicking on the Select tools icon, which should list all the available Codacy tools.

JetBrains IDEs

Supported Operating Systems

• macOS
• Linux
• Windows (via WSL)

Important

For Windows users: Windows WSL (a feature that allows you to run a Linux environment directly on Windows, without the need for a virtual machine or dual-boot setup) is the only way you can use this feature for now, but we're still working to fully support Windows. Only local analysis are supported for Windows, as MCP support for JetBrains IDEs is still not completely done.

Supported IDEs

• IntelliJ IDEA
• PyCharm
• PhpStorm
• Others in the suite

Note

For JetBrains IDEs, IntelliJ isn't the only supported editor, but is our primary focus. If you use other editors such as PyCharm and run into any issues, feel free to open an issue in our extension's repository. Check the extension page on the marketplace to see the full list of supported IDEs.

Built-in Scanners

• Trivy
• Semgrep
• ESLint
• Pylint
• PMD
• dartanalyzer
• Lizard
• Revive

How to install - JetBrains Quick Guide

Note for Windows users:

To take advantage of Codacy Guardrails on Windows, you need to set up WSL first; check the steps here. Only local analysis are supported for Windows, as MCP support for JetBrains IDEs is still not completely done.

1. Install the extension

You can either install the dependency from the JetBrains marketplace or search for it directly in your Codacy plugin's settings.

Note

If you don’t see the Codacy plugin icon on the left taskbar after installing it, go to View > Tool Windows > Codacy

2. Install and activate the Codacy CLI for local analysis

Click on the Codacy button on the lower right part of your IDE, and click Install CLI

It will create a folder in your local repository called .codacy with all needed configuration:

• The configuration from all built-in scanners
• Codacy CLI script to run analysis locally

Note

If you don't want this folder to be part of your repository in future commits but continue working with it locally, please add .codacy to your .gitignore file

Note

The IDE extension will ignore any CLI version already installed (for example, through brew or other package manager) on the machine.

3. Install MCP Server

a. Add the Codacy MCP Server

After clicking on the Codacy icon on the lower right of the editor, click on Install AiAgent MCP

b. Check if the Codacy MCP Server is enabled

In your IntelliJ settings, search the settings for the agent of your choice (Junie or Copilot) and confirm that Codacy is listed on the MCP settings tab.

Note

You need to install the plugin for your desired agent. Make sure to install JetBrains Junie or GitHub Copilot if you want to integrate the Codacy MCP.

c. Confirm the settings of your Codacy extension

In your IntelliJ settings, search the settings for the Codacy extension and confirm that you're using the correct version of the CLI, as well as your preferred AI agent.

If you want Codacy to generate the AI agent guidelines (which will instruct the agent to run the Codacy local analysis on changes, for example) for you, you should also enable this option in the editor settings.

d. Generate AI guidelines

Install the guidelines by clicking on Install AiAgent Guidelines on the Codacy icon on the lower right part of your IDE.

Note

You need to install the plugin for your desired agent. Make sure to install JetBrains Junie or GitHub Copilot if you want to integrate the Codacy MCP.

4. Restart your IDE to apply changes

5. After everything is set up, you should now be able to interact with Codacy via AI chat.

• Remember that for you to be able to interact with the Codacy MCP server, you must be on the Agent mode of the chat (Code on Junie), not Ask nor Edit mode.

6. Start using your Agent and Codacy will be there with you!

Share your feedback 📢

Did this page help you?

Yes No

Thanks for the feedback! Is there anything else you'd like to tell us about this page?

Send 255 characters left

We're sorry to hear that. Please let us know what we can improve:

Send 255 characters left

Alternatively, you can create a more detailed issue on our GitHub repository.

Thanks for helping improve the Codacy documentation.

Edit this page on GitHub if you notice something wrong or missing.

If you have a question or need help please contact support@codacy.com.

Last modified August 28, 2025