> ## Documentation Index
> Fetch the complete documentation index at: https://docs.semgrep.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect AI agents to Semgrep AppSec Platform (beta)

> Connect Claude Code, Codex, Cursor, VS Code, or another MCP client to Semgrep AppSec Platform to work with findings, scans, and policies.

Semgrep AppSec Platform provides a hosted Model Context Protocol (MCP) server. Connect your AI agent to the hosted MCP server to search and triage findings, generate fixes, debug scans, and manage policies from your editor or terminal.

> [!NOTE]
>
> This page covers the hosted MCP server for AppSec Platform. It's separate from the local Semgrep MCP server that Semgrep Guardian runs with `semgrep mcp`. For that server, see [Semgrep Guardian overview](https://docs.semgrep.dev/semgrep-guardian/overview.md).

With the hosted MCP server, you can:

* Search and filter findings, triage them in bulk, and read finding history.
* Generate fixes, inspect failed scans, and start new scans.
* Look up projects, dependencies, and advisories.
* Test rules, manage policies, and open Jira or Linear tickets.

If your agent only needs to investigate, connect it to the [read-only URL](#read-only-url) instead. It provides only the tools that read data.

Available tools depend on your role or token scope, your organization's plan, and the URL you connect to. For more information, see [Available capabilities](#available-capabilities).

## Prerequisites

* An AppSec Platform account in an organization on a Teams or Enterprise plan, including trials.
* An MCP client that supports remote servers over HTTP, such as Claude Code, Codex, Cursor, or VS Code.

## Server URLs

Use the URL for your deployment type:

| Deployment | MCP server URL | Read-only URL |
| :- | :- | :- |
| Multi-tenant | `https://semgrep.dev/api/mcp` | `https://semgrep.dev/api/mcp/read-only` |
| Single-tenant | `https://YOUR_TENANT.semgrep.dev/api/mcp` | `https://YOUR_TENANT.semgrep.dev/api/mcp/read-only` |

Replace `YOUR_TENANT` with your single-tenant subdomain. The examples on this page use the multi-tenant MCP server URL.

If you open either URL in a browser, Semgrep shows a page with setup instructions.

### Read-only URL

The read-only URL provides only the tools that read data, plus the `discover`, `semgrep_account`, and `semgrep_app_link` tools. It doesn't provide tools that make changes, such as triaging findings, generating fixes, applying policies, configuring rules, creating tickets, or starting scans and workflows. The `semgrep_run_job` tool isn't available, and the `discover` tool suggests only read tools.

To connect to the read-only URL, follow the steps in [Connect with OAuth](#connect-with-oauth) or [Connect with an API token](#connect-with-an-api-token), and replace `/api/mcp` with `/api/mcp/read-only`. If you also connect to the full MCP server URL, give each server a different name. For example, in Claude Code:

```bash theme={null}
claude mcp add --transport http --scope user semgrep-read-only https://semgrep.dev/api/mcp/read-only
```

> [!NOTE]
>
> The read-only URL limits which tools your client sees and can call. It doesn't limit your credentials: both URLs accept the same OAuth sign-in and API tokens. To also limit what the credential can do, connect with a **Read-only** API token. See [Token scopes](#token-scopes).

## How authentication works

The hosted MCP server uses your existing permissions. Each tool call uses the same API route as AppSec Platform. Semgrep checks your permissions on that route, as it does for any other request.

You can authenticate with OAuth or with an API token:

| | OAuth (recommended) | API token |
| :- | :- | :- |
| How you sign in | Sign in through your browser, then select an organization. | Add an `Authorization: Bearer YOUR_SEMGREP_APP_TOKEN` header to your client configuration. |
| Permissions | Your role in the organization you selected. | The token's scope, capped by the role of the token's owner. |
| Organization | The organization you selected when you signed in. | The organization the token was created in. |
| Switch organizations | Reconnect and select another organization. | Use a token from the other organization. |

## Connect with OAuth

OAuth is the recommended way to connect. You add the server to your client, then sign in through your browser and select a Semgrep organization.

> [!NOTE]
>
> **Single-tenant URL**
>
> The steps below use `https://semgrep.dev/api/mcp`. On a single-tenant deployment, replace that URL with `https://YOUR_TENANT.semgrep.dev/api/mcp`. Use your subdomain for `YOUR_TENANT`.

> [tab] Claude Code
>
> **Step 1**
>
> Add the server at user scope so that it's available in every project:
>
> ```bash theme={null}
> claude mcp add --transport http --scope user semgrep https://semgrep.dev/api/mcp
> ```
>
> If `semgrep` is already configured, update its existing entry instead of adding it again.
>
> **Step 2**
>
> Start Claude Code and run `/mcp`.
>
> **Step 3**
>
> Select `semgrep`.
>
> **Step 4**
>
> Sign in and select an organization in your browser.
>
> **Step 5**
>
> Run `/mcp` again and confirm that `semgrep` is connected.
>
> For more information, see [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp).

> [tab] Codex
>
> **Step 1**
>
> Add this entry to `~/.codex/config.toml`, or update the existing `semgrep` entry:
>
> ```toml theme={null}
> [mcp_servers.semgrep]
> url = "https://semgrep.dev/api/mcp"
> ```
>
> **Step 2**
>
> Start the browser sign-in:
>
> ```bash theme={null}
> codex mcp login semgrep
> ```
>
> **Step 3**
>
> Sign in and select an organization in your browser.
>
> **Step 4**
>
> Start a new Codex session, or reload the MCP servers in the Codex app. Run `/mcp` and confirm that `semgrep` is connected.
>
> For more information, see [OpenAI MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

> [tab] Cursor
>
> **Step 1**
>
> Add the server to `~/.cursor/mcp.json` to make it available in every project, or to `.cursor/mcp.json` in a single project:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "semgrep": {
>       "url": "https://semgrep.dev/api/mcp"
>     }
>   }
> }
> ```
>
> **Step 2**
>
> Open Cursor Settings and find `semgrep` under **Custom MCP Servers**.
>
> **Step 3**
>
> Start sign-in for `semgrep`.
>
> **Step 4**
>
> Sign in and select an organization in your browser.
>
> **Step 5**
>
> Confirm that `semgrep` shows as connected and lists its tools.
>
> For more information, see [Cursor MCP documentation](https://cursor.com/docs/mcp).

> [tab] VS Code
>
> **Step 1**
>
> Run **MCP: Open User Configuration** from the Command Palette to add the server for every workspace, or create `.vscode/mcp.json` in a single workspace. Add the following:
>
> ```json theme={null}
> {
>   "servers": {
>     "semgrep": {
>       "type": "http",
>       "url": "https://semgrep.dev/api/mcp"
>     }
>   }
> }
> ```
>
> **Step 2**
>
> Run **MCP: List Servers** from the Command Palette and select `semgrep`.
>
> **Step 3**
>
> Start the `semgrep` server.
>
> **Step 4**
>
> When VS Code prompts you to authenticate, sign in and select an organization in your browser.
>
> **Step 5**
>
> Run **MCP: List Servers** again and confirm that `semgrep` is running. Semgrep tools are available in Copilot Chat **Agent** mode.
>
> For more information, see [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).

> [tab] Other MCP clients
>
> Any MCP client that supports the Model Context Protocol's streamable HTTP transport and OAuth can connect. Configure the client with:
>
> * **Transport:** streamable HTTP
> * **URL:** `https://semgrep.dev/api/mcp`
> * **Authentication:** OAuth
>
> When the client starts the OAuth flow, sign in and select an organization in your browser. For where to add the server, see your client's documentation.
>
> If your client supports only local servers over standard input/output (stdio), use a bridge such as [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), a third-party npm package:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "semgrep": {
>       "command": "npx",
>       "args": ["-y", "mcp-remote", "https://semgrep.dev/api/mcp"]
>     }
>   }
> }
> ```

## Connect with an API token

Use an API token if you prefer to manage the credential yourself, or if your client doesn't support OAuth.

### Token scopes

Create a token in [**Settings > Tokens > API tokens**](https://semgrep.dev/orgs/-/settings/tokens/api). The token's scope determines which tools work:

| Token scope | What the hosted MCP server can do |
| :- | :- |
| Web API | All read and write operations. |
| Read-only | Read operations only. |
| Agent (CI) | Read and write operations on scans. |
| Member | Not supported. |
| CLI token from `semgrep login` | Policy, rule scope, and workflow schedule tools; source code manager (SCM), Slack, and ticketing settings; and scan reads. |

For more information, see [Access tokens](https://docs.semgrep.dev/deployment/tokens.md).

For the examples below, use a **Web API** or **Read-only** token. Where the client supports it, these examples read the token from the `SEMGREP_APP_TOKEN` environment variable. The token stays out of the configuration file.

> [!WARNING]
>
> Treat the token like a password. Don't commit configuration files that contain it to version control.

> [!NOTE]
>
> **Single-tenant URL**
>
> The steps below use `https://semgrep.dev/api/mcp`. On a single-tenant deployment, replace that URL with `https://YOUR_TENANT.semgrep.dev/api/mcp`. Use your subdomain for `YOUR_TENANT`.

> [tab] Claude Code
>
> **Step 1**
>
> Add the server with an `Authorization` header:
>
> ```bash theme={null}
> claude mcp add --transport http --scope user semgrep https://semgrep.dev/api/mcp \
>   --header "Authorization: Bearer YOUR_SEMGREP_APP_TOKEN"
> ```
>
> Replace `YOUR_SEMGREP_APP_TOKEN` with your API token. If `semgrep` is already configured, update the `Authorization` header in its existing entry instead of adding it again.
>
> **Step 2**
>
> Start a new Claude Code session. Run `/mcp` and confirm that `semgrep` is connected.

> [tab] Codex
>
> **Step 1**
>
> Add this entry to `~/.codex/config.toml` instead of the OAuth entry:
>
> ```toml theme={null}
> [mcp_servers.semgrep]
> url = "https://semgrep.dev/api/mcp"
> bearer_token_env_var = "SEMGREP_APP_TOKEN"
> ```
>
> Codex sends the value of `SEMGREP_APP_TOKEN` as a bearer token. Export `SEMGREP_APP_TOKEN` in the environment where you start Codex.
>
> **Step 2**
>
> Start a new Codex session, or reload the MCP servers in the Codex app. Run `/mcp` and confirm that `semgrep` is connected. You don't need to sign in through your browser.

> [tab] Cursor
>
> **Step 1**
>
> Add the server to `~/.cursor/mcp.json` or `.cursor/mcp.json` with an `Authorization` header:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "semgrep": {
>       "url": "https://semgrep.dev/api/mcp",
>       "headers": {
>         "Authorization": "Bearer ${env:SEMGREP_APP_TOKEN}"
>       }
>     }
>   }
> }
> ```
>
> Cursor replaces `${env:SEMGREP_APP_TOKEN}` with the value of the `SEMGREP_APP_TOKEN` environment variable. Export it in the environment where you start Cursor.
>
> **Step 2**
>
> Restart Cursor. In Cursor Settings, under **Custom MCP Servers**, confirm that `semgrep` shows as connected and lists its tools.

> [tab] VS Code
>
> **Step 1**
>
> Add the server to your user configuration or `.vscode/mcp.json` with an input that prompts for the token:
>
> ```json theme={null}
> {
>   "inputs": [
>     {
>       "type": "promptString",
>       "id": "semgrep-app-token",
>       "description": "Semgrep API token",
>       "password": true
>     }
>   ],
>   "servers": {
>     "semgrep": {
>       "type": "http",
>       "url": "https://semgrep.dev/api/mcp",
>       "headers": {
>         "Authorization": "Bearer ${input:semgrep-app-token}"
>       }
>     }
>   }
> }
> ```
>
> **Step 2**
>
> Start the `semgrep` server.
>
> **Step 3**
>
> Enter your API token when VS Code prompts for it. VS Code stores the value securely for later sessions.
>
> **Step 4**
>
> Run **MCP: List Servers** from the Command Palette and confirm that `semgrep` is running.

> [tab] Other MCP clients
>
> Configure the client with:
>
> * **Transport:** streamable HTTP
> * **URL:** `https://semgrep.dev/api/mcp`
> * **Header:** `Authorization: Bearer YOUR_SEMGREP_APP_TOKEN`
>
> Replace `YOUR_SEMGREP_APP_TOKEN` with your API token.
>
> If your client supports only local servers over stdio, pass the header through `mcp-remote`. The following example stores the token in the configuration file. Keep that file out of version control.
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "semgrep": {
>       "command": "npx",
>       "args": [
>         "-y",
>         "mcp-remote",
>         "https://semgrep.dev/api/mcp",
>         "--header",
>         "Authorization:${SEMGREP_AUTH_HEADER}"
>       ],
>       "env": {
>         "SEMGREP_AUTH_HEADER": "Bearer YOUR_SEMGREP_APP_TOKEN"
>       }
>     }
>   }
> }
> ```

## Available capabilities

The hosted MCP server provides tools in the following areas. Which tools you can use depends on your role or token scope, your organization's plan, and the URL you connect to.

On the [read-only URL](#read-only-url), each area provides only its read tools. For example, you can search findings, read scan logs, test patterns, and dry-run policies, but you can't triage findings, generate fixes, or start scans.

| Capability | What you can do |
| :- | :- |
| Findings and triage | Search and filter findings from Semgrep Code, Semgrep Supply Chain, Semgrep Secrets, and Semgrep Agentic Workflows. Count findings by severity, project, or rule. Triage, ignore, and reopen findings one at a time or in bulk, and add notes to them. Read code snippets and finding history. |
| Fixes | Generate [Autofix](https://docs.semgrep.dev/semgrep-code/triage-remediation/autofix.md) suggestions, start Autofix jobs, and reuse your organization's [Memories](https://docs.semgrep.dev/semgrep-multimodal/overview#memories). |
| Scans | Find failed scans, read scan logs and errors, and retry scans. Start rule-based scans, [AI-powered detection](https://docs.semgrep.dev/semgrep-code/ai-powered-detection-concepts) scans, and [Agentic Workflows](https://docs.semgrep.dev/workflows/overview.md) jobs. See [Run Semgrep jobs](#run-semgrep-jobs). |
| Projects | List projects, and look up a project or branch. |
| Supply chain | Look up advisories, list dependencies, and find the repositories that an advisory affects. |
| Rules and policies | Search the Semgrep Registry, test patterns against code, dry-run and apply policies, manage project and tag exceptions to your policies, and configure Guardian rules. |
| Reports | Get backlog by severity, product, or rule, median open age, findings activity, and [secure guardrails](https://docs.semgrep.dev/secure-guardrails/secure-guardrails-in-semgrep) adoption. |
| Agentic Workflows | Trigger workflows, schedule them for one project or many at once, read job status and task logs, and track credit usage. Only admins can trigger or schedule workflows. |
| Integrations and automations | Create and link Jira and Linear tickets, and build automations. View Slack notification settings, and check and sync SCM connections. |
| Settings | View and update your organization's product settings, and view a project's Managed Scans settings. |

Both URLs also provide a `discover` tool that your agent can call to find the right tool for a task, a `semgrep_account` tool that returns the organization you're connected to, and a `semgrep_app_link` tool that builds links to pages in AppSec Platform. The full MCP server URL also provides a `FeedbackService_SendFeedback` tool, which your agent can use to send feedback about the hosted MCP server to the Semgrep team.

The hosted MCP server also publishes a `semgrep-automations` skill through the [MCP skills extension](https://modelcontextprotocol.io/seps/2640-skills-extension). The skill guides your agent through scheduling Agentic Workflows and setting up the automations that act on their findings.

### Run Semgrep jobs

Use the `semgrep_run_job` tool to start a scan or workflow on a project and get a summary of the findings it produces. Set `jobType` to choose what runs:

| `jobType` | What runs | Required inputs |
| :- | :- | :- |
| `sms` | A rule-based scan with Semgrep Managed Scans. | A project. |
| `aiDetection` | An AI-powered detection scan. Set `baseBranch` to scan only the changes compared to that branch. | A project. |
| `workflow` | An Agentic Workflows run. | A project and `workflowName`. |
| `deep` | A scan with Managed Scans, an AI-powered detection scan, and your organization's Agentic Workflows, all on one branch. | A project. |

To choose the branch, set `branch`. Otherwise, the job runs on the branch that Managed Scans uses for full scans of the project, or on the project's primary branch if no full-scan branch is set.

AI-powered detection scans and Agentic Workflows runs consume credits.

> [!NOTE]
>
> Only admins can run `workflow` and `deep` jobs, because both run Agentic Workflows. The `semgrep_run_job` tool isn't available on the read-only URL.

Scans can take several minutes, so `semgrep_run_job` uses the [MCP tasks extension](https://modelcontextprotocol.io/extensions/tasks/overview). Instead of waiting for the job to finish, the tool returns a task right away. Your MCP client checks the task until the job is completed, failed, or canceled, then reads the result. The result describes the job and summarizes the findings from each scan or workflow that ran. Tasks expire 24 hours after they're created.

The `semgrep_run_job` tool appears only if your MCP client supports the tasks extension. If you don't see it, check your client's documentation for tasks support.

You can cancel a `workflow` job. You can't stop a Managed Scans or AI-powered detection scan after it starts, so `sms`, `aiDetection`, and `deep` jobs keep running until they finish.

## Troubleshooting

### The connection fails with "Invalid or expired bearer token"

The client receives a `401` error. The token was revoked, was created in a different deployment than the server URL, or has the **Member** scope.

To fix this, use a token with the **Web API** scope from the same deployment as the server URL, or connect with OAuth.

### Only the `semgrep_account` tool appears

The connection isn't tied to an organization that can use the hosted MCP server. Either your organization is on the Free plan, or you connected with a token that isn't bound to an organization.

To fix this, connect to an organization on a Teams or Enterprise plan. If you use an API token, create it in that organization's [**Settings > Tokens > API tokens**](https://semgrep.dev/orgs/-/settings/tokens/api).

### A tool returns "status 404: The requested URL was not found"

Your token or role doesn't have the permission that the tool requires. The hosted MCP server reports permission denials as `404`, not `403`, even for an organization you belong to.

To fix this, check [Token scopes](#token-scopes), or switch to a **Web API** token or OAuth.

### Autofix returns `AUTOFIX_ERROR_TYPE_PERMISSION_DENIED`

**Read-only** tokens can't open Autofix pull requests. Use a **Web API** token or OAuth.

### A tool returns "Please upgrade your plan" or "Writes through this API are not yet enabled"

Your organization's plan or feature settings don't include this operation. Changing the token doesn't fix this error. Contact your Semgrep account team.

### A capability you expect is missing

If you connected to the [read-only URL](#read-only-url), tools that make changes aren't available. To triage findings, generate fixes, or start scans, connect to the full MCP server URL instead.

Not every AppSec Platform feature is available through the hosted MCP server. To request a capability, contact [Semgrep support](https://docs.semgrep.dev/support.md).