> ## Documentation Index
> Fetch the complete documentation index at: https://semgrep-ee9d73d8-abhijna-tec-605-update-docs-to-clarify-cla.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Semgrep Guardian: AI coding agent security plugin
> Set up Semgrep Guardian to scan AI-generated code and catch security issues before they ship.
Semgrep Guardian integrates natively with AI coding agents like Claude Code and Cursor to catch security issues before they ship. It bundles the Semgrep MCP server, Hooks, and Skills into a single install, and scans every file an agent generates using Semgrep Code, Supply Chain, and Secrets. When findings are detected, the agent is prompted to regenerate code until Semgrep returns clean results or you choose to dismiss them.
Claude Code uses Semgrep's hosted remote server and authenticates through OAuth, so developers don't need to install or run the Semgrep CLI. Every other supported IDE runs Semgrep through a locally installed CLI. See [Authentication](#authentication) for details on sign-in and enterprise rollout.
The plugin uses each IDE's native hook or MCP system:
* **Claude Code**: [hooks](https://code.claude.com/docs/en/hooks) and [plugins](https://code.claude.com/docs/en/plugins)
* **Codex**: [MCP](https://developers.openai.com/codex/mcp)
* **Cursor**: [hooks](https://cursor.com/docs/hooks) and [MCP](https://cursor.com/docs/mcp)
* **GitHub Copilot** (Visual Studio, JetBrains, Xcode, Eclipse): [MCP](https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp-in-your-ide/extend-copilot-chat-with-mcp)
* **Kiro**: [MCP](https://kiro.dev/docs/mcp/)
* **VS Code**: [MCP](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
* **Devin** (Windsurf): [Cascade hooks](https://docs.windsurf.com/windsurf/cascade/hooks)
This guide covers setup for each of the preceding products listed, but the plugin works with any MCP client.
## Prerequisites
* A Semgrep account
## Authentication
How you sign in depends on which IDE you use.
**Claude Code (remote scans):** The plugin handles authentication through OAuth. Each developer completes a one-time browser login when they first use the plugin. Semgrep refreshes access tokens automatically, so developers rarely need to sign in again.
**Other IDEs:** These integrations run Semgrep through a locally installed CLI. Each developer signs in with `semgrep login`, which opens a browser-based login flow. See [Install the Semgrep CLI](#install-the-semgrep-cli).
### CLI and OAuth credentials
Guardian stores credentials in two local files under `~/.semgrep/`:
* `settings.yml`: written when you sign in through `semgrep login` or set an API token manually. This is the same file the Semgrep CLI uses.
* `guardian.yml`: written when you sign in through OAuth in the remote Claude Code plugin.
If you are already logged in through `semgrep login`, Guardian can use the credentials from `settings.yml`. For the remote Claude Code plugin, Guardian checks for OAuth credentials in `guardian.yml` first. If OAuth credentials are present, Guardian uses them instead of any API token in `settings.yml`.
At startup, Guardian fetches its default authentication method from Semgrep's remote server. OAuth is currently the default for users who are not yet signed in. This setting is global and not configurable per user.
If you are switching from a local CLI setup to the remote Claude Code plugin, keep in mind that an existing OAuth session in `guardian.yml` takes precedence over CLI credentials in `settings.yml`. If scans run under a different account than you expect, check which file contains active credentials. Use [`semgrep logout`](/getting-started/cli#log-out) to remove CLI credentials from `settings.yml`.
To sign in with the legacy API-token method in Claude Code, ask the Guardian MCP to log in to Semgrep using the legacy method.
Semgrep may disable API-token login for Guardian in the future, but there are no definite plans as of now.
### Enterprise rollout
Shared API tokens and service accounts are not recommended for Guardian. Each developer should authenticate individually through OAuth for Claude Code or `semgrep login` for local CLI integrations.
For Claude Code with remote scans, OAuth helps Semgrep associate activity with the correct user and avoids the risks of shared credentials.
Semgrep discourages sharing app or API tokens across a team because:
* Revoking a shared token affects every user who depends on it.
* Shared credentials are rate-limited as a single user, which can throttle scans when many developers run Guardian concurrently.
If you set an API token in `~/.semgrep/settings.yml`, Guardian can use it when no OAuth session exists in `guardian.yml`. Semgrep does not recommend this pattern for enterprise rollouts.
## Connect to your IDE
Claude Code uses Semgrep's hosted remote server by default, so you do not need to install the Semgrep CLI locally.
Start a Claude Code instance:
```bash theme={null}
claude
```
Open the plugin manager:
```bash theme={null}
/plugin
```
Go to **Discover**, search for **Semgrep**, and click **Install**.
Tell Claude to load the plugin:
```bash theme={null}
/reload-plugins
```
Start a new session in Claude to begin the OAuth login flow:
```bash theme={null}
/clear
```
The plugin registers a post-tool hook so Claude Code scans every file it writes. Learn more about [Claude Code plugins](https://code.claude.com/docs/en/plugins) and [hooks](https://code.claude.com/docs/en/hooks).
The remote server is the recommended default. If you need to run Semgrep locally instead, you can install the local plugin from the [`semgrep/guardian-local`](https://github.com/semgrep/guardian-local) repo.
[Install the Semgrep CLI](#install-the-semgrep-cli).
Start a Claude Code instance:
```bash theme={null}
claude
```
Add the Semgrep marketplace:
```bash theme={null}
/plugin marketplace add semgrep/guardian-local
```
Install the plugin from the marketplace:
```bash theme={null}
/plugin install semgrep@semgrep-marketplace
```
Tell Claude to load the plugin:
```bash theme={null}
/reload-plugins
```
Set up the plugin:
```bash theme={null}
/setup-semgrep-plugin
```
[Install the Semgrep CLI](#install-the-semgrep-cli).
Update your `~/.codex/config.toml` file and paste the following:
```bash theme={null}
[mcp_servers.semgrep]
command = "semgrep"
args = ["mcp"]
```
Codex does not expose a post-write hook, so Semgrep tools are surfaced through MCP and invoked when the agent calls them. Learn more about [Codex MCP configuration](https://developers.openai.com/codex/mcp).
[Install the Semgrep CLI](#install-the-semgrep-cli).
Find Semgrep in the [Cursor Plugin Marketplace](https://cursor.com/marketplace/semgrep), or open **Cursor > ⌘⇧J > Plugins**. Search "Semgrep" and click **Add to Cursor**.
Restart Cursor to apply configuration.
In Cursor's chat, run the `/setup-semgrep-plugin` skill to finish wiring up the plugin.
The plugin uses [Cursor hooks](https://cursor.com/docs/hooks) (`afterFileEdit` and `stop`) to scan code as the agent writes it, and exposes Semgrep tools through [Cursor MCP](https://cursor.com/docs/mcp).
Use this tab for GitHub Copilot in Visual Studio, JetBrains IDEs, Xcode, or Eclipse. (For Copilot in VS Code, use the **VS Code** tab.)
[Install the Semgrep CLI](#install-the-semgrep-cli).
Register the Semgrep MCP server with your IDE's Copilot configuration. The JSON shape is the same across IDEs:
```json theme={null}
{
"servers": {
"semgrep": {
"command": "semgrep",
"args": ["mcp"]
}
}
}
```
Follow your IDE's instructions for *where* to put this entry: [Extending Copilot Chat with MCP servers](https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp-in-your-ide/extend-copilot-chat-with-mcp) covers Visual Studio, JetBrains, Xcode, and Eclipse.
Restart your IDE and open Copilot Chat. Semgrep tools become available in **Agent** mode.
Copilot does not expose a post-write hook, so Semgrep tools are invoked when the agent calls them through MCP.
[Install the Semgrep CLI](#install-the-semgrep-cli).
Add the Semgrep MCP server to VS Code. Create `.vscode/mcp.json` in your workspace (or run the **MCP: Open User Configuration** command from the Command Palette for a user-wide entry) and paste the following:
```json theme={null}
{
"servers": {
"semgrep": {
"command": "semgrep",
"args": ["mcp"]
}
}
}
```
Reload VS Code. Semgrep tools become available in the Copilot Chat **Agent** mode.
VS Code does not expose a post-write hook today, so Semgrep tools are invoked when the agent calls them through MCP. Learn more about [adding and managing MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).
[Install the Semgrep CLI](#install-the-semgrep-cli).
Create a `hooks.json` file at `~/.codeium/windsurf/hooks.json` and paste the following configuration:
```json theme={null}
{
"hooks": {
"post_write_code": [
{
"command": "semgrep mcp -k post-tool-cli-scan -a windsurf",
"show_output": true
}
]
}
}
```
Restart Windsurf to apply hook configuration.
The `post_write_code` event fires after Cascade writes or modifies any file. Learn more about [Windsurf Cascade hooks](https://docs.windsurf.com/windsurf/cascade/hooks).
Kiro uses your locally installed Semgrep CLI to run Semgrep on your machine, so [install the Semgrep CLI](#install-the-semgrep-cli) first. Clicking the box below opens Kiro directly so you can add the server; it will not open a new browser tab.
[](https://kiro.dev/launch/mcp/add?name=semgrep\&config=%7B%22command%22%3A%22semgrep%22%2C%22args%22%3A%5B%22mcp%22%5D%2C%22env%22%3A%7B%22SEMGREP_APP_TOKEN%22%3A%22%24%7BSEMGREP_TOKEN%7D%22%7D%7D)
Alternatively, follow the [Kiro MCP docs](https://kiro.dev/docs/mcp/) and add this file to your `.kiro/settings/mcp.json`:
```json theme={null}
{
"mcpServers": {
"semgrep": {
"command": "semgrep",
"args": ["mcp"],
"env": {
"SEMGREP_APP_TOKEN": "${SEMGREP_TOKEN}"
}
}
}
}
```
See [Kiro docs](https://kiro.dev/docs/mcp/) for more info.
[Install the Semgrep CLI](#install-the-semgrep-cli), then add the Semgrep MCP Server to your IDE. Semgrep provides [sample configuration information](https://github.com/semgrep/semgrep/tree/develop/cli/src/semgrep/mcp#integrations) that you can use as a starting point. Refer to your IDE's documentation for specific details on where to add the MCP server configuration.
If your IDE supports a post-write or post-tool hook, point it at `semgrep mcp -k post-tool-cli-scan -a ` to scan generated code automatically. The Windsurf tab above shows this pattern.
## Install the Semgrep CLI
This section applies only if you use an IDE other than Claude Code, or if you run the [local Claude Code plugin](#run-semgrep-guardian-locally). Claude Code's default remote plugin handles authentication through OAuth and does not require a local CLI.
Install the Semgrep CLI using Homebrew, pipx, or uv. This requires Python 3.10 or later (the Semgrep CLI needs it at runtime regardless of how it was installed):
```bash theme={null}
# install using Homebrew
brew install semgrep
# or, install using pipx (https://pipx.pypa.io/stable/how-to/install-pipx/)
pipx install semgrep
# or, install using uv (https://docs.astral.sh/uv/)
uv tool install semgrep
```
Verify that you've installed the [latest version](https://github.com/semgrep/semgrep/releases) of Semgrep:
```bash theme={null}
semgrep --version
```
Sign in to your Semgrep account and install the Semgrep Pro engine:
```bash theme={null}
semgrep login && semgrep install-semgrep-pro
```
`semgrep login` launches a browser window. You can also use the activation link printed in the terminal.
## Enterprise deployment guide
To roll out Semgrep Guardian across an organization, standardize the install so every developer's agent picks up the plugin automatically instead of relying on each developer to install it by hand.
### Use your agent's built-in enterprise controls
Most coding agents let you pin an approved marketplace or plugin for your whole team. This is the simplest way to make Guardian available (or required) everywhere:
* **Claude Code**: [Require marketplaces for your team](https://code.claude.com/docs/en/plugin-marketplaces#require-marketplaces-for-your-team)
* **Cursor**: [Team marketplaces](https://cursor.com/docs/plugins#team-marketplaces)
### Deploy through a mobile device management (MDM) platform for more granularity
Deploy through your MDM platform to scope rollout by device group, or to combine Guardian with other managed configuration deployed via your MDM. Anthropic maintains a set of [MDM deployment examples and best practices](https://github.com/anthropics/claude-code/tree/main/examples/mdm) that cover managed settings for macOS (`.plist` and `.mobileconfig` profiles via Jamf, Kandji, and similar) and Windows (PowerShell file deployment or ADMX/registry policy via Intune and Group Policy), along with how to verify that managed settings are applied.
### Get help with a custom rollout
Reach out if you want help building something custom for your MDM or agent fleet. You can find us in Semgrep's `#mcp` [Slack community](https://go.semgrep.dev/slack) or check out our [support options](/support).
## Additional resources
* Semgrep's `#mcp` [Slack community](https://go.semgrep.dev/slack)
* The [Semgrep MCP server repo on GitHub](https://github.com/semgrep/semgrep/tree/develop/cli/src/semgrep/mcp)