diff --git a/docs/docs.json b/docs/docs.json index b9bc195182..4832909e1e 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -80,7 +80,12 @@ { "group": "Prowler for AI Agents", "pages": [ - "getting-started/products/prowler-claude-code-plugin" + "user-guide/ai-agents/index", + "user-guide/ai-agents/claude-code", + "user-guide/ai-agents/claude-desktop", + "user-guide/ai-agents/codex", + "user-guide/ai-agents/cursor", + "user-guide/ai-agents/vscode" ] } ] @@ -217,7 +222,12 @@ { "group": "Prowler for AI Agents", "pages": [ - "getting-started/products/prowler-claude-code-plugin" + "user-guide/ai-agents/index", + "user-guide/ai-agents/claude-code", + "user-guide/ai-agents/claude-desktop", + "user-guide/ai-agents/codex", + "user-guide/ai-agents/cursor", + "user-guide/ai-agents/vscode" ] }, { @@ -660,6 +670,10 @@ { "source": "/user-guide/tutorials/prowler-cloud-public-ips", "destination": "/security/networking" + }, + { + "source": "/getting-started/products/prowler-claude-code-plugin", + "destination": "/user-guide/ai-agents/claude-code" } ] } diff --git a/docs/getting-started/basic-usage/prowler-mcp.mdx b/docs/getting-started/basic-usage/prowler-mcp.mdx index 120e5c038b..0a4c7fec04 100644 --- a/docs/getting-started/basic-usage/prowler-mcp.mdx +++ b/docs/getting-started/basic-usage/prowler-mcp.mdx @@ -23,6 +23,28 @@ Most users should use the **Cloud MCP Server** — it needs no installation and - **Cloud MCP Server (HTTP)**: the managed server at `https://mcp.prowler.com/mcp` (or your own self-hosted HTTP server). - **Local MCP Server (STDIO)**: local installation only (runs as a subprocess of your MCP client). +### Step-by-Step Guides Per Agent + +The tabs below are a quick configuration reference. For a walkthrough with screenshots, troubleshooting, and client-specific caveats, follow the dedicated guide for your agent: + + + + Plugin vs. MCP-only, and which Claude surfaces work + + + The Chat tab, via a local bridge + + + CLI and the VS Code extension + + + Global and project scopes + + + Agent mode with secure key prompts + + + ## Cloud MCP Server Configuration (Recommended) Connect to the **Cloud MCP Server** at `https://mcp.prowler.com/mcp` over HTTP. This is the recommended path — no installation, always up to date. The same configuration works for a self-hosted HTTP server: just swap the URL. @@ -76,67 +98,6 @@ Connect to the **Cloud MCP Server** at `https://mcp.prowler.com/mcp` over HTTP. The `mcp-remote` tool acts as a bridge for clients that don't support HTTP natively. Learn more at [mcp-remote on npm](https://www.npmjs.com/package/mcp-remote). - - - 1. Open Claude Desktop settings - 2. Go to "Developer" tab - 3. Click in "Edit Config" button - 4. Edit the `claude_desktop_config.json` file with your favorite editor - 5. Install a reviewed version of `mcp-remote` in a dedicated local workspace: - ```bash - mkdir -p ~/.local/share/prowler-mcp-bridge - cd ~/.local/share/prowler-mcp-bridge - npm init -y - npm install --save-exact mcp-remote@0.1.38 - ``` - 6. Add the following configuration: - ```json - { - "mcpServers": { - "prowler": { - "command": "/absolute/path/to/.local/share/prowler-mcp-bridge/node_modules/.bin/mcp-remote", - "args": [ - "https://mcp.prowler.com/mcp", - "--header", - "Authorization: Bearer ${PROWLER_API_KEY}" - ], - "env": { - "PROWLER_API_KEY": "" - } - } - } - } - ``` - - - - Run the following command: - ```bash - export PROWLER_API_KEY="" - claude mcp add --transport http prowler https://mcp.prowler.com/mcp --header "Authorization: Bearer $PROWLER_API_KEY" --scope user - ``` - - - - 1. Open Cursor settings - 2. Go to "Tools & MCP" - 3. Click in "New MCP Server" button - 4. Add to the JSON Configuration the following: - ```json - { - "mcpServers": { - "prowler": { - "url": "https://mcp.prowler.com/mcp", - "headers": { - "Authorization": "Bearer " - } - } - } - } - ``` - - - ## Local MCP Server Configuration diff --git a/docs/getting-started/products/index.mdx b/docs/getting-started/products/index.mdx index c14ea37471..d8def66737 100644 --- a/docs/getting-started/products/index.mdx +++ b/docs/getting-started/products/index.mdx @@ -18,7 +18,7 @@ Read the [public announcement of the Prowler product families](https://prowler-w | Prowler Private Cloud | Prowler Cloud deployed in your own environment. Formerly Prowler Enterprise. See [pricing](https://prowler.com/pricing). | | [Prowler Hub](https://hub.prowler.com) | Free public library of versioned checks, cloud service artifacts, and compliance frameworks. | | [Prowler Lighthouse AI](/getting-started/products/prowler-cloud-lighthouse) | AI security analyst capabilities within Prowler Cloud and Prowler Private Cloud. | -| [Prowler MCP](/getting-started/products/prowler-mcp) | MCP server that connects AI assistants and agents to Prowler, including IDE plugins such as [Prowler for Claude Code](/getting-started/products/prowler-claude-code-plugin). | +| [Prowler MCP](/getting-started/products/prowler-mcp) | MCP server that connects AI assistants and agents to Prowler, including IDE plugins such as [Prowler for Claude Code](/user-guide/ai-agents/claude-code). | {/* Unreleased products. Uncomment these rows in the Prowler Products table when announced: | Prowler Registry | Distribution service for Prowler content such as checks and compliance frameworks. Free and paid tiers. | diff --git a/docs/getting-started/products/prowler-claude-code-plugin.mdx b/docs/getting-started/products/prowler-claude-code-plugin.mdx deleted file mode 100644 index 99c92a1488..0000000000 --- a/docs/getting-started/products/prowler-claude-code-plugin.mdx +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: 'Prowler for Claude Code' -sidebarTitle: 'Claude Code' ---- - -End-to-end cloud security and compliance from inside [Claude Code](https://www.claude.com/product/claude-code), powered by the [Prowler MCP server](/getting-started/products/prowler-mcp). The plugin lets Claude walk a Prowler Cloud-connected account through a compliance assessment and remediate findings until the chosen security or industry framework is compliant. - - -**Preview**: this plugin is under active development. Please report issues on [GitHub](https://github.com/prowler-cloud/prowler/issues) or join the [Slack community](https://goto.prowler.com/slack) for feedback. - - -## Requirements - - - - Installed and signed in. See the [official install guide](https://www.claude.com/product/claude-code). - - - The free tier is enough to start. Sign up at [cloud.prowler.com](https://cloud.prowler.com). - - - Create one at [cloud.prowler.com/profile](https://cloud.prowler.com/profile). - - - -## Installation - - - - Inside a Claude Code session: - - ```text - /plugin marketplace add prowler-cloud/prowler - /plugin install prowler@prowler-plugins - ``` - - - If you already have the repository checked out: - - ```text - /plugin marketplace add /absolute/path/to/prowler - /plugin install prowler@prowler-plugins - ``` - - - -## Configuration - -On first install, Claude Code prompts for your **Prowler API key**. The value is stored securely (macOS keychain or `~/.claude/.credentials.json`) and used to authenticate against Prowler Cloud. - - -To rotate the key, uninstall and reinstall the plugin — Claude Code will prompt again. - - -## Verify the installation - -In a Claude Code session: - -```text -/mcp → "prowler" appears as a connected server -/plugin → "prowler" enabled, skill listed as prowler:framework-compliance-triage -``` - -If `/mcp` reports the `prowler` server as failed, the most common cause is a rejected API key — re-issue one in Prowler Cloud and reinstall the plugin so it re-prompts. - -## Usage - -Open a conversation that mentions the framework you want to comply with. Examples: - -- *"Make my AWS production account compliant with CIS 4.0."* -- *"Make my current Terraform project compliant with Prowler ThreatScore Compliance Framework based on the latest scan results."* -- *"Help me get to 100% on PCI-DSS for this GCP project."* - -You pick a **primary tool** (Terraform, gh / az / aws CLI, web console, or mixed) and a **mode**: - - - - Claude shows each fix — target resource, exact commands, side effects, reversibility — and waits for your go-ahead before applying. - - - Claude presents a single up-front plan grouped by shared fixes, waits for one confirmation, then proceeds. It pauses mid-loop if a fix has wide blast radius or a finding is not applicable. - - - -Claude tracks progress in a markdown report under `.prowler/` at your project root — one file per framework × account. Open it any time to see exactly where the flow is. When all findings are addressed, Claude proposes a fresh Prowler scan to verify everything end-to-end. - -## Uninstalling - -```text -/plugin uninstall prowler@prowler-plugins -/plugin marketplace remove prowler-plugins -``` - -The stored API key is removed automatically. - -## Troubleshooting - -| Symptom | Likely cause | Fix | -| --- | --- | --- | -| `/mcp` shows `prowler` as failed | Rejected API key | Generate a new one in Prowler Cloud and reinstall the plugin to re-prompt. | -| Skill not invoked when expected | The skill description didn't match the prompt | Mention the framework name plus "compliance" or "compliant" in your prompt. | -| "Framework not supported" | Prowler Hub does not list the framework for that provider | Open an issue or PR at [github.com/prowler-cloud/prowler](https://github.com/prowler-cloud/prowler). | diff --git a/docs/getting-started/products/prowler-mcp.mdx b/docs/getting-started/products/prowler-mcp.mdx index 93159b2e7d..a30c4e5488 100644 --- a/docs/getting-started/products/prowler-mcp.mdx +++ b/docs/getting-started/products/prowler-mcp.mdx @@ -26,7 +26,7 @@ The fastest way to get started is the **Cloud MCP Server** at `https://mcp.prowl ``` - Step-by-step setup for Claude Desktop, Claude Code, Cursor, and other clients. + Step-by-step setup for Claude Code, Codex, Cursor, VS Code, and other agents. diff --git a/docs/images/prowler-mcp/claude/claude-code-mcp-add.png b/docs/images/prowler-mcp/claude/claude-code-mcp-add.png new file mode 100644 index 0000000000..2f5894219c Binary files /dev/null and b/docs/images/prowler-mcp/claude/claude-code-mcp-add.png differ diff --git a/docs/images/prowler-mcp/claude/claude-code-mcp-command.png b/docs/images/prowler-mcp/claude/claude-code-mcp-command.png new file mode 100644 index 0000000000..c036ce8b61 Binary files /dev/null and b/docs/images/prowler-mcp/claude/claude-code-mcp-command.png differ diff --git a/docs/images/prowler-mcp/claude/claude-code-prowler-query.png b/docs/images/prowler-mcp/claude/claude-code-prowler-query.png new file mode 100644 index 0000000000..f78f5286e6 Binary files /dev/null and b/docs/images/prowler-mcp/claude/claude-code-prowler-query.png differ diff --git a/docs/images/prowler-mcp/claude/claude-desktop-developer-settings.png b/docs/images/prowler-mcp/claude/claude-desktop-developer-settings.png new file mode 100644 index 0000000000..494661238b Binary files /dev/null and b/docs/images/prowler-mcp/claude/claude-desktop-developer-settings.png differ diff --git a/docs/images/prowler-mcp/claude/claude-desktop-prowler-tools.png b/docs/images/prowler-mcp/claude/claude-desktop-prowler-tools.png new file mode 100644 index 0000000000..30d0ad7be8 Binary files /dev/null and b/docs/images/prowler-mcp/claude/claude-desktop-prowler-tools.png differ diff --git a/docs/images/prowler-mcp/codex/codex-app-mcp-servers.png b/docs/images/prowler-mcp/codex/codex-app-mcp-servers.png new file mode 100644 index 0000000000..3b735864f9 Binary files /dev/null and b/docs/images/prowler-mcp/codex/codex-app-mcp-servers.png differ diff --git a/docs/images/prowler-mcp/codex/codex-mcp-slash-command.png b/docs/images/prowler-mcp/codex/codex-mcp-slash-command.png new file mode 100644 index 0000000000..df3f8a65b3 Binary files /dev/null and b/docs/images/prowler-mcp/codex/codex-mcp-slash-command.png differ diff --git a/docs/images/prowler-mcp/codex/codex-prowler-query.png b/docs/images/prowler-mcp/codex/codex-prowler-query.png new file mode 100644 index 0000000000..b225933cfd Binary files /dev/null and b/docs/images/prowler-mcp/codex/codex-prowler-query.png differ diff --git a/docs/images/prowler-mcp/cursor/cursor-customize-page.png b/docs/images/prowler-mcp/cursor/cursor-customize-page.png new file mode 100644 index 0000000000..8afe41c1c5 Binary files /dev/null and b/docs/images/prowler-mcp/cursor/cursor-customize-page.png differ diff --git a/docs/images/prowler-mcp/cursor/cursor-mcp-json.png b/docs/images/prowler-mcp/cursor/cursor-mcp-json.png new file mode 100644 index 0000000000..79814b4db4 Binary files /dev/null and b/docs/images/prowler-mcp/cursor/cursor-mcp-json.png differ diff --git a/docs/images/prowler-mcp/cursor/cursor-prowler-connected.png b/docs/images/prowler-mcp/cursor/cursor-prowler-connected.png new file mode 100644 index 0000000000..ae946abdc5 Binary files /dev/null and b/docs/images/prowler-mcp/cursor/cursor-prowler-connected.png differ diff --git a/docs/images/prowler-mcp/cursor/cursor-prowler-query.png b/docs/images/prowler-mcp/cursor/cursor-prowler-query.png new file mode 100644 index 0000000000..3bdec29a36 Binary files /dev/null and b/docs/images/prowler-mcp/cursor/cursor-prowler-query.png differ diff --git a/docs/images/prowler-mcp/vscode/vscode-agent-tools.png b/docs/images/prowler-mcp/vscode/vscode-agent-tools.png new file mode 100644 index 0000000000..e1d90719d6 Binary files /dev/null and b/docs/images/prowler-mcp/vscode/vscode-agent-tools.png differ diff --git a/docs/images/prowler-mcp/vscode/vscode-command-palette.png b/docs/images/prowler-mcp/vscode/vscode-command-palette.png new file mode 100644 index 0000000000..453e973a36 Binary files /dev/null and b/docs/images/prowler-mcp/vscode/vscode-command-palette.png differ diff --git a/docs/images/prowler-mcp/vscode/vscode-list-servers.png b/docs/images/prowler-mcp/vscode/vscode-list-servers.png new file mode 100644 index 0000000000..596a6af443 Binary files /dev/null and b/docs/images/prowler-mcp/vscode/vscode-list-servers.png differ diff --git a/docs/images/prowler-mcp/vscode/vscode-mcp-json.png b/docs/images/prowler-mcp/vscode/vscode-mcp-json.png new file mode 100644 index 0000000000..01fbf91768 Binary files /dev/null and b/docs/images/prowler-mcp/vscode/vscode-mcp-json.png differ diff --git a/docs/style.css b/docs/style.css index 9a1ed19a0f..edbb1fbfcf 100644 --- a/docs/style.css +++ b/docs/style.css @@ -84,6 +84,7 @@ li[data-title="Prowler Lighthouse AI"] > button span:first-child::after, li[data-title="Providers"] > button span:first-child::after, li[data-title="Scans"] > button span:first-child::after, li[data-title="Prowler MCP"] > button span:first-child::after, +li[data-title="Prowler for AI Agents"] > button span:first-child::after, div:has(+ ul a[href="/security/encryption"]) h3 span::after, li[id="/user-guide/compliance/tutorials/cross-provider-compliance"] a > div > div > span:first-child::after, li[id="/user-guide/tutorials/prowler-alerts"] a > div > div > span:first-child::after, diff --git a/docs/user-guide/ai-agents/claude-code.mdx b/docs/user-guide/ai-agents/claude-code.mdx new file mode 100644 index 0000000000..84763bf173 --- /dev/null +++ b/docs/user-guide/ai-agents/claude-code.mdx @@ -0,0 +1,294 @@ +--- +title: "Connect Claude Code to Prowler MCP Server" +sidebarTitle: "Claude Code" +--- + +Connect [Claude Code](https://www.claude.com/product/claude-code) to the Prowler Cloud MCP Server at `https://mcp.prowler.com/mcp`. + +## Where Claude Code Runs + +Claude Code runs in two places. Both read the same configuration file, so you set it up **once from a terminal** and it works in both. + +| Surface | How you open it | Reads | Covered by | +|---|---|---|---| +| **Claude Code CLI** | `claude` in a terminal | `~/.claude.json` | This guide | +| **Claude Code in the desktop app** | The **Code** tab inside the Claude app | `~/.claude.json` — the same file | This guide, [set up from a terminal](#claude-code-in-the-desktop-app-code-tab) | +| **Claude app Chat** | The **Chat** tab inside the Claude app | `claude_desktop_config.json` | [Claude App Chat](/user-guide/ai-agents/claude-desktop) — a separate setup | + + +**The Chat tab is not Claude Code.** It is a different product surface with its own configuration file and its own connection method (a local bridge). Nothing on this page applies to it. If you want Prowler in Chat, use the [Claude App Chat](/user-guide/ai-agents/claude-desktop) guide instead. + + +## Choose Your Setup + +There are two ways to connect. Both end with the same MCP Server connection, the difference is what comes with it. + +| | 🔌 **Prowler Plugin** | ⚙️ **MCP Connection Only** | +|---|---|---| +| **What you get** | The MCP connection **plus** the official Prowler skills for cloud security tasks | The MCP connection | +| **Setup** | Two slash commands, prompts for the API key | One `claude mcp add` command | +| **Guided workflows** | ✅ Skills drive multi-step security work end to end | ❌ You drive the conversation | +| **Best for** | Structured cloud security work, such as taking an account to compliance | Ad-hoc queries and your own workflows | +| **Where to use it** | Claude Code CLI | Claude Code CLI, and the **recommended setup for the desktop app's [Code tab](#claude-code-in-the-desktop-app-code-tab)** | + + +**The plugin already includes the MCP connection.** If you install the plugin, do **not** also run `claude mcp add` — you would end up with the server configured twice. + + +## Prerequisites + +- **Claude Code** installed and signed in. See the [official install guide](https://www.claude.com/product/claude-code). +- **A Prowler Cloud account.** The free tier is enough to start. Sign up at [cloud.prowler.com](https://cloud.prowler.com). + +## Get Your Prowler API Key + +Create an API key in Prowler Cloud and copy it. The key begins with `pk_` and is shown only once. Check the [API Keys](/user-guide/tutorials/prowler-app-api-keys#creating-api-keys) guide for details. + +--- + +# Option 1: Install the Prowler Plugin + + +**Preview**: this plugin is under active development. Please report issues on [GitHub](https://github.com/prowler-cloud/prowler/issues) or join the [Slack community](https://goto.prowler.com/slack) for feedback. + + +End-to-end cloud security from inside Claude Code, powered by the Prowler MCP server. The plugin bundles the official Prowler skills, task-specific workflows that let Claude carry out multi-step security work against a Prowler Cloud-connected account, rather than answering one question at a time. + +### Included Skills + +| Skill | What it does | +| --- | --- | +| `prowler:framework-compliance-triage` | Walks an account through a compliance assessment and remediates findings until the chosen security or industry framework is compliant. | + + +More skills are on the way. Installing the plugin keeps you current — new skills arrive with plugin updates, no extra configuration required. + + +## Installation (Claude Code CLI) + + + + Inside a Claude Code session: + + ```text + /plugin marketplace add prowler-cloud/prowler + /plugin install prowler@prowler-plugins + ``` + + + If you already have the repository checked out: + + ```text + /plugin marketplace add /absolute/path/to/prowler + /plugin install prowler@prowler-plugins + ``` + + + +On first install, Claude Code prompts for your **Prowler API key**. The value is stored securely (macOS keychain or `~/.claude/.credentials.json`) and used to authenticate against Prowler Cloud. + +## Verify the Installation + +In a Claude Code session: + +```text +/mcp → "prowler" appears as a connected server +/plugin → "prowler" enabled, with the bundled Prowler skills listed +``` + +If `/mcp` reports the `prowler` server as failed, the most common cause is a rejected API key, re-issue one in Prowler Cloud and reinstall the plugin so it re-prompts. + +## Usage + +Describe the security task you want done and Claude selects the matching skill. + +### Framework Compliance Triage + +Mention the framework you want to comply with: + +- *"Make my AWS production account compliant with CIS 4.0."* +- *"Make my current Terraform project compliant with Prowler ThreatScore Compliance Framework based on the latest scan results."* +- *"Help me get to 100% on PCI-DSS for this GCP project."* + +You pick a **primary tool** (Terraform, gh / az / aws CLI, web console, or mixed) and a **mode**: + + + + Claude shows each fix — target resource, exact commands, side effects, reversibility — and waits for your go-ahead before applying. + + + Claude presents a single up-front plan grouped by shared fixes, waits for one confirmation, then proceeds. It pauses mid-loop if a fix has wide blast radius or a finding is not applicable. + + + +Claude tracks progress in a markdown report under `.prowler/` at your project root — one file per framework × account. Open it any time to see exactly where the flow is. When all findings are addressed, Claude proposes a fresh Prowler scan to verify everything end-to-end. + +## Uninstalling + +```text +/plugin uninstall prowler@prowler-plugins +/plugin marketplace remove prowler-plugins +``` + +The stored API key is removed automatically. + +--- + +# Option 2: Connect the MCP Server Only + +Choose this when you want Prowler's tools available without the Prowler skills. + +## Add the Server + +Claude Code connects to remote HTTP MCP servers natively and supports custom headers, so no bridge is required. + +```bash +export PROWLER_API_KEY="pk_your_api_key_here" + +claude mcp add --transport http prowler https://mcp.prowler.com/mcp \ + --header "Authorization: Bearer $PROWLER_API_KEY" \ + --scope user +``` + + + Terminal showing the claude mcp add command and its confirmation output + + + +**Always pass `--scope user`.** The default scope is `local`, which binds the server to the single directory you ran the command in. A locally-scoped server does not load when you open Claude Code anywhere else — this is the most common reason Prowler tools appear to vanish. + + +| Scope | Loads in | Shared | Stored in | +|-------|----------|--------|-----------| +| `user` | All your projects | No | `~/.claude.json`, top-level `mcpServers` | +| `project` | Current project only | Yes, via version control | `.mcp.json` in the project root | +| `local` (default) | Current project only | No | `~/.claude.json`, under that project's entry | + +When the same server name exists in more than one scope, precedence is **local → project → user**. The winning entry is used whole; fields are not merged. + + +Avoid `--scope project` for Prowler. That writes `.mcp.json` into your repository, and committing the file would publish your API key. + + + +**Local server:** Replace the URL with your own HTTP endpoint. Everything else stays the same. + + +## Verify the Connection + +```bash +claude mcp get prowler # shows which scope holds the definition +claude mcp list # lists all servers and their status +``` + +Inside a Claude Code session, run `/mcp` to see connected servers and their tools. + + + Claude Code session showing the /mcp command output with the Prowler server connected + + +## Start Using Prowler MCP + +- *"Show me all critical findings from my AWS accounts"* +- *"What does the S3 bucket public access check do?"* +- *"Onboard this new AWS account in my Prowler organization"* + + + Claude Code answering a question about critical findings using Prowler MCP tools + + +--- + +# Claude Code in the Desktop App (Code Tab) + +The **Code** tab in the Claude desktop app runs the same Claude Code as the CLI, and reads the same `~/.claude.json`. There is no separate Prowler setup for it — you configure it **from a terminal** and the Code tab picks it up. + + +**Use [Option 2](#option-2-connect-the-mcp-server-only) with `--scope user` here.** It is the recommended setup for the Code tab. The Prowler plugin ([Option 1](#option-1-install-the-prowler-plugin)) is not the recommended route for the desktop app — install it in the Claude Code CLI instead. + + + +**You cannot do this from inside the app.** The desktop app has no interface for adding an MCP server to a Claude Code session. **Settings → Connectors** configures the **Chat** tab, not the **Code** tab, so anything added there never reaches Claude Code. Trying to configure it from the app is the main reason this appears not to work. + + + + + In a normal terminal — not inside the app: + + ```bash + export PROWLER_API_KEY="pk_your_api_key_here" + + claude mcp add --transport http prowler https://mcp.prowler.com/mcp \ + --header "Authorization: Bearer $PROWLER_API_KEY" \ + --scope user + ``` + + `--scope user` is what makes this work. It writes to `~/.claude.json`, the file the Code tab reads. + + + + ```bash + claude mcp get prowler + ``` + + The scope must be `user`. A `local`-scoped server is bound to the directory you ran the command in and will not load in an app session opened elsewhere. + + + + Quit the app completely and reopen it. Configuration is read at startup. + + + + Open a **Code** tab session and ask for a Prowler tool: "Do you have access to the Prowler MCP tools?", it should respond with a list of available tools or confirming that it has access. + + + +--- + +# Claude App Chat (Chat Tab) + +Not covered by this page. The **Chat** tab is a separate surface: it does not read `~/.claude.json`, so a server added with `claude mcp add` appears in the CLI and in the Code tab but **never** in Chat. That is expected behavior, not a broken setup. + +Chat reads `claude_desktop_config.json` and reaches the Prowler MCP Server through a local bridge. + + + Separate guide: local bridge and its own configuration file + + +--- + +# Troubleshooting + +| Symptom | Likely cause | Fix | +| --- | --- | --- | +| `/mcp` shows `prowler` as failed | Rejected API key | Generate a new one in Prowler Cloud. With the plugin, reinstall it to re-prompt. | +| No MCP servers configured | Server added at `local` scope from another directory | Run `claude mcp get prowler`, then re-add with `--scope user`. | +| A stale entry overrides a working one | Precedence is local → project → user | `claude mcp remove prowler --scope local` | +| Tools appear in the CLI but not in the app's **Code** tab | Server added at `local` scope, or the app was not restarted | Re-add with `--scope user`, then quit and reopen the app. See [Claude Code in the Desktop App](#claude-code-in-the-desktop-app-code-tab). | +| Tools appear in the **Code** tab but not the **Chat** tab | Chat is a different surface with its own config file | Expected. Set Chat up separately, see [Claude App Chat](/user-guide/ai-agents/claude-desktop). | +| No way to add the server from inside the app | The app has no MCP interface for Claude Code sessions | Configure it from a terminal with `--scope user`, then restart the app. See [Claude Code in the Desktop App](#claude-code-in-the-desktop-app-code-tab). | +| Skill not invoked when expected | The prompt didn't match any skill's description | Name the task explicitly. For compliance triage, mention the framework plus "compliance" or "compliant". | +| "Framework not supported" | Prowler Hub does not list the framework for that provider | Open an issue or PR at [github.com/prowler-cloud/prowler](https://github.com/prowler-cloud/prowler). | + +### Authentication Fails With 401 + +- Confirm the header value includes the `Bearer ` prefix. +- Check that `PROWLER_API_KEY` was set when you ran `claude mcp add` — the shell expands it at that moment and stores the resulting literal value. If the variable was empty, the stored header reads `Bearer ` with nothing after it. Verify with `claude mcp get prowler`. +- Confirm the key has not been revoked in Prowler Cloud. + +## Next Steps + + + + Explore all available tools and capabilities + + + Configuration reference for every supported client + + + +## Getting Help + +- Search for existing [GitHub issues](https://github.com/prowler-cloud/prowler/issues) +- Ask for help in our [Slack community](https://goto.prowler.com/slack) +- Report a new issue on [GitHub](https://github.com/prowler-cloud/prowler/issues/new) diff --git a/docs/user-guide/ai-agents/claude-desktop.mdx b/docs/user-guide/ai-agents/claude-desktop.mdx new file mode 100644 index 0000000000..1a09c43116 --- /dev/null +++ b/docs/user-guide/ai-agents/claude-desktop.mdx @@ -0,0 +1,142 @@ +--- +title: "Connect the Claude App Chat to Prowler MCP Server" +sidebarTitle: "Claude App (Chat)" +--- + +Connect the **Chat** tab of the Claude desktop app to the Prowler Cloud MCP Server at `https://mcp.prowler.com/mcp`. + + +**This page covers the Chat tab only.** Looking for **Claude Code** — either the CLI or the app's **Code** tab? Those are a different surface, with a different configuration file and a different connection method. See [Connect Claude Code](/user-guide/ai-agents/claude-code). + + +## Prerequisites + +- **Claude desktop app** installed and signed in. +- **Node.js and npm**, to install the bridge. +- **A Prowler Cloud account.** The free tier is enough to start. Sign up at [cloud.prowler.com](https://cloud.prowler.com). + +## Why "Add Custom Connector" Does Not Work + +The app's **Settings → Connectors → Add custom connector** dialog is the obvious place to paste an MCP URL, but it does not fit the Prowler Cloud MCP Server for two independent reasons: + +1. **Connectors authenticate with OAuth.** Authenticating with a fixed API key sent as a request header is a separate mechanism that Anthropic documents as **beta**, rolled out on request. Without it, the dialog offers a URL and OAuth client credentials, with nowhere to supply `Authorization: Bearer pk_...`. +2. **Connectors do not connect from your machine.** Claude reaches your MCP server from Anthropic's cloud infrastructure rather than your local device. A Prowler MCP Server on `localhost`, behind a VPN, or restricted by an IP allowlist is unreachable that way regardless of authentication. + +Use a local bridge instead, as described below. + +## Step 1: Get Your Prowler API Key + +Create an API key in Prowler Cloud and copy it. The key begins with `pk_` and is shown only once. Check the [API Keys](/user-guide/tutorials/prowler-app-api-keys#creating-api-keys) guide for details. + +## Step 2: Install the Bridge + +`mcp-remote` presents the remote HTTP server to Claude as a local STDIO server and injects the `Authorization` header. Install a pinned version into a dedicated directory: + +```bash +mkdir -p ~/.local/share/prowler-mcp-bridge +cd ~/.local/share/prowler-mcp-bridge +npm init -y +npm install --save-exact mcp-remote@0.1.38 +``` + + +Do not configure Claude to run `npx mcp-remote` directly. `npx` can fetch and execute a new version on every launch, which means unreviewed code runs with access to your API key. Install a pinned version and point Claude at the installed binary. + + + +`mcp-remote` is community-maintained and is not an Anthropic product. Review it before use. + + +## Step 3: Edit the Configuration File + +In the Claude app, go to **Settings → Developer** and click **Edit Config**. This reveals `claude_desktop_config.json`: + +- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` +- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` + + + Claude app Settings Developer tab showing the Edit Config button + + +Add the following, replacing the `command` path with the absolute path to the installed binary and the placeholder with your API key: + +```json +{ + "mcpServers": { + "prowler": { + "command": "/absolute/path/to/.local/share/prowler-mcp-bridge/node_modules/.bin/mcp-remote", + "args": [ + "https://mcp.prowler.com/mcp", + "--header", + "Authorization: Bearer ${PROWLER_API_KEY}" + ], + "env": { + "PROWLER_API_KEY": "pk_your_api_key_here" + } + } + } +} +``` + + +**Local server:** Replace the URL with your own HTTP endpoint. Everything else stays the same. + + +## Step 4: Restart the App + +Quit the Claude app completely and reopen it. Configuration is read at startup. + +## Step 5: Start Using Prowler MCP + +Open a Chat conversation and ask questions that use the Prowler tools: + +- *"Show me all critical findings from my AWS accounts"* +- *"What does the S3 bucket public access check do?"* +- *"Summarize my CIS compliance status by provider"* + + + Claude app chat showing the Prowler MCP tools available + + +## Troubleshooting + +### Server Does Not Appear After Editing the Config + +- Quit and reopen the app entirely — closing the window is not enough on macOS. +- Confirm `claude_desktop_config.json` is valid JSON. +- Confirm the `command` path points at a real executable. A wrong path surfaces as the server failing to start rather than as an auth error. + +### Tools Appear in Claude Code but Not in Chat + +Expected. The Chat tab does not read `~/.claude.json`, so servers added with `claude mcp add` never appear here. The Chat tab needs an entry in `claude_desktop_config.json`, which is what this guide sets up. + +### Authentication Fails With 401 + +- Confirm the header value includes the `Bearer ` prefix. +- Confirm the key has not been revoked in Prowler Cloud. + +### Checking the Logs + +- **macOS:** `~/Library/Logs/Claude/mcp*.log` +- **Windows:** `%APPDATA%\Claude\logs\mcp*.log` + +```bash +tail -f ~/Library/Logs/Claude/mcp*.log +``` + +## Next Steps + + + + Explore all available tools and capabilities + + + Configuration reference for every supported client + + + +## Getting Help + +- Search for existing [GitHub issues](https://github.com/prowler-cloud/prowler/issues) +- Ask for help in our [Slack community](https://goto.prowler.com/slack) +- Report a new issue on [GitHub](https://github.com/prowler-cloud/prowler/issues/new) diff --git a/docs/user-guide/ai-agents/codex.mdx b/docs/user-guide/ai-agents/codex.mdx new file mode 100644 index 0000000000..4a346e999f --- /dev/null +++ b/docs/user-guide/ai-agents/codex.mdx @@ -0,0 +1,188 @@ +--- +title: "Connect Codex / ChatGPT Desktop to Prowler MCP Server" +sidebarTitle: "Codex / ChatGPT" +--- + +Connect [OpenAI Codex](https://learn.chatgpt.com/docs/extend/mcp) to the Prowler Cloud MCP Server at `https://mcp.prowler.com/mcp` so Codex can query findings, inspect checks, and manage your Prowler providers. + +## Which Codex Surfaces Work + +Codex keeps MCP servers in one file, `~/.codex/config.toml`. You can set it up from either the **Codex / ChatGPT desktop app** or the **Codex CLI** — both write to that same file, so pick whichever you already use. + +| Surface | Set it up here | Notes | +|---------|----------------|-------| +| **[Codex / ChatGPT desktop app](https://learn.chatgpt.com/docs/app)** (macOS, Windows) | ✅ Yes | **Settings → MCP servers** | +| **Codex CLI** (terminal) | ✅ Yes | `codex mcp` commands | +| **Codex IDE extension** (VS Code) | Inherits | Works automatically once the app or CLI is configured | +| **ChatGPT on the web** | ❌ No | Does not read local Codex configuration | + + +**Codex and ChatGPT share one desktop app.** Since July 2026 the standalone Codex app and the ChatGPT desktop app are the same application: Codex is a dedicated coding surface inside it, alongside Chat and Work. If you already had the Codex app, updating turns it into the new ChatGPT desktop app and it still opens in Codex. Either way, this guide applies. + +Not to be confused with **ChatGPT Classic**, the name given to the previous-generation ChatGPT desktop app. + + + +**Configure once, use everywhere.** The Codex documentation states that the ChatGPT desktop app, Codex CLI, and IDE extension "share this configuration. Once you configure your MCP servers, you can switch among those clients without redoing setup." Set the server up in the app or the CLI and the IDE extension picks it up with no extra work. + + +## Prerequisites + +- **The Codex / ChatGPT desktop app, or Codex CLI 0.46.0 or later.** Remote MCP servers over streamable HTTP were added to the CLI in 0.46.0 — check with `codex --version` and upgrade if needed. +- **A Prowler Cloud account.** The free tier is enough to start. Sign up at [cloud.prowler.com](https://cloud.prowler.com). + +## Step 1: Get Your Prowler API Key + +Create an API key in Prowler Cloud and copy it. The key begins with `pk_` and is shown only once. Check the [API Keys](/user-guide/tutorials/prowler-app-api-keys#creating-api-keys) guide for details. + +## Step 2: Add the Prowler MCP Server + +The Prowler MCP Server needs two request headers: `Authorization` to authenticate you, and `User-Agent` because Codex does not send one by default. + +Each tab below is a complete setup — follow the one that matches the surface you use. + + + + 1. Open **Settings** and select **Plugins → MCPs** + 2. Click **Add server** + 3. Enter `prowler` as the name and choose type **Streamable HTTP** + 4. Enter the URL `https://mcp.prowler.com/mcp` + 5. Add two headers: + + | Header | Value | + |--------|-------| + | `Authorization` | `Bearer pk_your_api_key_here` | + | `User-Agent` | `codex` | + + 6. Save the server + + + Codex / ChatGPT desktop app Settings showing the MCP servers panel with the Add server dialog and both headers filled in + + + + **Enter the key directly here rather than using an environment variable.** Codex can read credentials from an environment variable, but desktop applications do not reliably inherit variables exported in a shell profile — on macOS an app launched from Finder or the Dock typically sees none of them. Pasting the key into the dialog is the approach that works consistently in the app. + + + + **This stores your API key in plain text** in `~/.codex/config.toml`. Treat that file accordingly: exclude it from dotfile repositories and config sync, and create the key from an account with the minimum permissions you need so its exposure is limited. Revoke and re-issue the key in Prowler Cloud if the file is ever shared. + + + + + Register the server: + + ```bash + codex mcp add prowler --url https://mcp.prowler.com/mcp + ``` + + Codex confirms with `Added global MCP server 'prowler'.` + + Then add both headers by hand, since `codex mcp add` has no flag for headers. Open `~/.codex/config.toml` and complete the entry: + + ```toml + [mcp_servers.prowler] + url = "https://mcp.prowler.com/mcp" + http_headers = { Authorization = "Bearer pk_your_api_key_here", "User-Agent" = "codex" } + ``` + + + **Write the key literally rather than using an environment variable.** This is the form that works across every Codex surface. All of them read this same file, but only the CLI reliably sees variables exported in your shell profile — see the warning below. + + + + **This stores your API key in plain text** in `~/.codex/config.toml`. Treat that file accordingly: exclude it from dotfile repositories and config sync, and create the key from an account with the minimum permissions you need so its exposure is limited. Revoke and re-issue the key in Prowler Cloud if the file is ever shared. + + + + +Restart Codex once you are done. + + +**Local server:** Replace the URL with your own HTTP endpoint. Everything else stays the same. + + +## Step 3: Verify the Connection + +Run `/mcp` in the app or in a CLI session to list connected servers and their tools. + + + Codex composer showing the /mcp command output with Prowler tools listed + + +From the CLI you can also inspect the stored entry directly: + +```bash +codex mcp list # one row per server, with status and auth +codex mcp get prowler # full entry, header values masked +``` + + +**Verify rather than assume.** Codex silently ignores unrecognized keys in `config.toml` — a misspelled key name produces no error at all, and the server simply never receives your credentials. Always confirm with `codex mcp get prowler` after editing the file by hand. + + +## Step 4: Start Using Prowler MCP + +Ask Codex questions that use the Prowler tools: + +- *"Show me all critical findings from my AWS accounts"* +- *"What does the S3 bucket public access check do?"* +- *"List my connected Prowler providers and their last scan date"* + + + Codex answering a question about critical findings using Prowler MCP tools + + +## Troubleshooting + +### Startup Fails With HTTP 403 Forbidden + +Codex reports a handshake failure on startup, with an HTML error page rather than a JSON response: + +``` +⚠ MCP client for `prowler` failed to start: MCP startup failed: handshaking with MCP server + failed: ... unexpected server response: HTTP 403: + 403 Forbidden +``` + +The `User-Agent` header is missing. Codex's HTTP client does not send one, and requests without it are rejected before reaching the MCP server. Note this is a **403**, not a 401 — so it is not an API key problem. Add the header as shown in [Step 2](#step-2-add-the-prowler-mcp-server); the value itself does not matter, only that the header is present. + +### Authentication Fails With 401 + +- Run `codex mcp get prowler` and confirm the entry has the headers you expect. Values are masked, but a missing header shows as `-`. +- If you used a literal header, confirm the value starts with `Bearer ` and contains the full key. +- **If it works in the CLI but fails in the desktop app or the VS Code extension, you are almost certainly using an environment variable.** Those surfaces do not inherit your shell profile. Switch that entry to a literal `Authorization` header as shown in [Step 2](#step-2-add-the-prowler-mcp-server). +- If you use an environment variable, verify it is set in the environment Codex was launched from: `echo $PROWLER_API_KEY`. +- With `env_http_headers` the variable must include the `Bearer ` prefix. With `bearer_token_env_var` it must **not** — Codex adds the prefix itself. +- Confirm the key has not been revoked in Prowler Cloud. + +### Server Not Listed + +- Confirm your Codex CLI version is 0.46.0 or later with `codex --version`. +- Run `codex mcp get prowler`. If it reports the server is not found, the entry was not written or the TOML table name is misspelled. +- Check for a typo in the key names. Codex ignores unknown keys without warning. + +### Project-Scoped Config Is Ignored + +A `.codex/config.toml` inside a project is loaded **only when the project is trusted**. If your entry lives there and does nothing, trust the project or move the entry to `~/.codex/config.toml`. + +### Tools Do Not Appear After Editing the Config + +Restart Codex. Configuration is read at startup. In the app, quit completely and reopen it, sometimes just clous the window is not enough. + +## Next Steps + + + + Explore all available tools and capabilities + + + Configuration reference for every supported client + + + +## Getting Help + +- Search for existing [GitHub issues](https://github.com/prowler-cloud/prowler/issues) +- Ask for help in our [Slack community](https://goto.prowler.com/slack) +- Report a new issue on [GitHub](https://github.com/prowler-cloud/prowler/issues/new) diff --git a/docs/user-guide/ai-agents/cursor.mdx b/docs/user-guide/ai-agents/cursor.mdx new file mode 100644 index 0000000000..5e28eeeb1f --- /dev/null +++ b/docs/user-guide/ai-agents/cursor.mdx @@ -0,0 +1,171 @@ +--- +title: "Connect Cursor to Prowler MCP Server" +sidebarTitle: "Cursor" +--- + +Connect [Cursor](https://cursor.com/docs/mcp) to the Prowler Cloud MCP Server at `https://mcp.prowler.com/mcp` so the Cursor agent can query findings, inspect security checks, and manage your Prowler providers while you work. + +Cursor supports remote MCP servers over HTTP natively, so no bridge or local installation is required. + +## Prerequisites + +- **Cursor** installed and authenticated. See the [official install guide](https://cursor.com/download). +- **A Prowler Cloud account.** The free tier is enough to start. Sign up at [cloud.prowler.com](https://cloud.prowler.com). + +## Step 1: Get Your Prowler API Key + +Create an API key in Prowler Cloud and copy it. The key begins with `pk_` and is shown only once. Check the [API Keys](/user-guide/tutorials/prowler-app-api-keys#creating-api-keys) guide for details. + +## Step 2: Add the Prowler MCP Server + +Cursor reads MCP servers from an `mcp.json` file. Choose the scope that fits your use case: + +| Scope | File | Applies to | +|-------|------|------------| +| **Global** | `~/.cursor/mcp.json` | Every project you open in Cursor | +| **Project** | `.cursor/mcp.json` in the project root | That project only | + +Both files are merged. If the same server name appears in both, the project-level entry takes priority. + +For Prowler, the **global** scope is usually the right choice — your findings are not tied to a single repository, and it keeps the API key out of any project directory that might be committed. + + + + From Agent Window open **Customize** in the Cursor sidebar, then select the MCP section. + + On earlier versions, press `Cmd + Shift + J` (macOS) or `Ctrl + Shift + J` (Windows/Linux) to open Cursor Settings, then click **Tools & MCP** in the sidebar. + + + + + + Click **New MCP Server** (or **Add Custom MCP**). Cursor opens `mcp.json` in the editor. + + + Cursor Customize page with the MCP section open + + + + + Paste the following, replacing the placeholder with your API key: + + ```json + { + "mcpServers": { + "prowler": { + "url": "https://mcp.prowler.com/mcp", + "headers": { + "Authorization": "Bearer " + } + } + } + } + ``` + + Save the file. Cursor picks up the change and connects to the server. + + + Cursor editor showing the completed mcp.json with the Prowler server entry + + + + + +**Local server:** Replace the URL with your own HTTP endpoint. Everything else stays the same. + + +### Keeping the API Key Out of the File + +Cursor resolves variables in the `command`, `args`, `env`, `url`, and `headers` fields, so you can reference an environment variable instead of writing the key into `mcp.json`: + +```json +{ + "mcpServers": { + "prowler": { + "url": "https://mcp.prowler.com/mcp", + "headers": { + "Authorization": "Bearer ${env:PROWLER_API_KEY}" + } + } + } +} +``` + +Export the variable in your shell profile (`~/.zshrc`, `~/.bashrc`, or equivalent): + +```bash +export PROWLER_API_KEY="pk_your_api_key_here" +``` + + +The syntax is `${env:NAME}`, not a bare `${NAME}`. Restart Cursor after changing your shell profile so it inherits the new value. + + + +The `envFile` option does **not** work for remote servers — it is STDIO-only. Use `${env:...}` interpolation with variables set in your shell profile instead. + + +This form is strongly recommended when using a **project-scoped** `.cursor/mcp.json`, since that file may be committed to version control. + +## Step 3: Verify the Connection + +Return to the MCP settings. The `prowler` server should be listed as enabled, with the Prowler tools shown beneath it. + + + Cursor MCP settings showing the Prowler server connected with its tools listed + + +## Step 4: Start Using Prowler MCP + +Open the chat panel and ask questions that use the Prowler tools: + +- *"Show me all critical findings from my AWS accounts"* +- *"What does the S3 bucket public access check do?"* +- *"Which of my providers failed the most CIS checks in the last scan?"* + +Cursor asks for approval before running an MCP tool the first time. + + + Cursor chat answering a question about critical findings using Prowler MCP tools + + +You can toggle individual tools on or off from the tools list at the top of the chat panel, which is useful for keeping the active tool count down. + +## Troubleshooting + +### Server Does Not Connect + +- Check that `mcp.json` is valid JSON. A trailing comma or missing brace prevents the whole file from loading. +- Open **MCP Logs** in the Output panel for the specific error. +- Confirm the URL is exactly `https://mcp.prowler.com/mcp`. + +### Authentication Fails With 401 + +- Verify the header value includes the `Bearer ` prefix: `"Bearer pk_..."`, not just the key. +- Confirm the key has not been revoked in Prowler Cloud. +- If using `${env:PROWLER_API_KEY}`, check the variable is set in the environment Cursor inherits. Restart Cursor after editing your shell profile — a value exported only in an already-open terminal will not reach the app. + +### The Entire `mcp.json` Is Ignored + +Remove any `"type": "streamable-http"` field. One such entry causes the Cursor CLI to drop every server in the file silently. + +### Some Prowler Tools Are Missing + +Cursor limits how many tools it exposes to the agent at once. With several MCP servers enabled you may exceed it, and some tools become unavailable. Disable servers you are not using, or turn off individual tools from the chat panel's tools list. + +## Next Steps + + + + Explore all available tools and capabilities + + + Configuration reference for every supported client + + + +## Getting Help + +- Search for existing [GitHub issues](https://github.com/prowler-cloud/prowler/issues) +- Ask for help in our [Slack community](https://goto.prowler.com/slack) +- Report a new issue on [GitHub](https://github.com/prowler-cloud/prowler/issues/new) diff --git a/docs/user-guide/ai-agents/index.mdx b/docs/user-guide/ai-agents/index.mdx new file mode 100644 index 0000000000..ca05419050 --- /dev/null +++ b/docs/user-guide/ai-agents/index.mdx @@ -0,0 +1,49 @@ +--- +title: "Connect Your AI Agent to Prowler" +sidebarTitle: "Overview" +description: "Pick your AI agent and follow its guide to connect it to the Prowler Cloud MCP Server." +--- + +Connect your AI agent to the Prowler Cloud MCP Server at `https://mcp.prowler.com/mcp` so it can query findings, inspect security checks, and manage your Prowler providers. + +Pick your agent below. Each guide is a full walkthrough with screenshots, verification steps, and the caveats specific to that client. + + + + Plugin and MCP-only choices, and which Claude surfaces work + + + The Chat tab, via a local bridge + + + ChatGPT Desktop App, Codex CLI, the VS Code extension through same config file + + + Agentic code editor. Global and project scopes + + + Agent mode with secure key prompts + + + +## Before You Start + +All guides need the same two things: + +- A **Prowler Cloud account** with at least one cloud provider connected. [Sign up](https://cloud.prowler.com) if you do not have one. +- A **Prowler API key**, created in Prowler Cloud. The key begins with `pk_` and is shown only once. See the [API Keys](/user-guide/tutorials/prowler-app-api-keys#creating-api-keys) guide. + + +Using an agent that is not listed here? Any MCP-compatible client can connect. See the [generic configuration reference](/getting-started/basic-usage/prowler-mcp#cloud-mcp-server-configuration-recommended) for the raw connection details. + + +## Next Steps + + + + How the MCP Server fits into Prowler + + + Cloud and local server options, all clients + + diff --git a/docs/user-guide/ai-agents/vscode.mdx b/docs/user-guide/ai-agents/vscode.mdx new file mode 100644 index 0000000000..90f41e5816 --- /dev/null +++ b/docs/user-guide/ai-agents/vscode.mdx @@ -0,0 +1,145 @@ +--- +title: "Connect VS Code and GitHub Copilot to Prowler MCP Server" +sidebarTitle: "VS Code / Copilot" +--- + +Connect [Visual Studio Code](https://code.visualstudio.com/docs/agents/reference/mcp-configuration) and GitHub Copilot agent mode to the Prowler Cloud MCP Server at `https://mcp.prowler.com/mcp` so Copilot can query findings, inspect security checks, and manage your Prowler providers. + +## Prerequisites + +- **VS Code 1.102 or later.** MCP support became generally available in 1.102. +- **GitHub Copilot** enabled, with access to agent mode. +- **A Prowler Cloud account.** The free tier is enough to start. Sign up at [cloud.prowler.com](https://cloud.prowler.com). + +## Step 1: Get Your Prowler API Key + +Create an API key in Prowler Cloud and copy it. The key begins with `pk_` and is shown only once. Check the [API Keys](/user-guide/tutorials/prowler-app-api-keys#creating-api-keys) guide for details. + +## Step 2: Add the Prowler MCP Server + +VS Code stores MCP servers in an `mcp.json` file. Choose the scope that fits your use case: + +| Scope | How to open it | Applies to | +|-------|----------------|------------| +| **User** | Command palette → **MCP: Open User Configuration** | Every workspace | +| **Workspace** | `.vscode/mcp.json` in the project root | That workspace only | + +For Prowler, the **user** scope is usually the right choice — your findings are not tied to a single repository, and it keeps the API key out of any project directory that might be committed. + + + + Open the command palette with `Cmd + Shift + P` (macOS) or `Ctrl + Shift + P` (Windows/Linux), then run **MCP: Open User Configuration**. + + VS Code opens your user-level `mcp.json`. Use this command rather than navigating to the file by hand — the file lives inside your active profile folder, and the path differs per profile. + + + VS Code command palette showing the MCP: Open User Configuration command + + + + + Paste the following. This version prompts you for the API key on first use and stores it securely, so the key is never written into the file: + + ```json + { + "inputs": [ + { + "type": "promptString", + "id": "prowler-api-key", + "description": "Prowler API Key", + "password": true + } + ], + "servers": { + "prowler": { + "type": "http", + "url": "https://mcp.prowler.com/mcp", + "headers": { + "Authorization": "Bearer ${input:prowler-api-key}" + } + } + } + } + ``` + + Save the file. + + + VS Code editor showing the completed mcp.json with the Prowler server entry + + + + + Start the server. VS Code prompts for the Prowler API key. Paste it and press Enter — VS Code stores it securely and does not ask again. + + + + + +**The root key is `servers`, not `mcpServers`.** VS Code uses a different schema from Cursor, Claude, and most other clients. Copying a `mcpServers` snippet from elsewhere silently fails to register the server. + + + +**Local server:** Replace the URL with your own HTTP endpoint. Everything else stays the same. + + +## Step 3: Verify the Connection + +Run **MCP: List Servers** from the command palette. The `prowler` server should appear as running. + + + VS Code MCP: List Servers output showing the Prowler server running + + +Select the server to start, stop, or restart it, and to view its output log if the connection fails. + +## Step 4: Start Using Prowler MCP + +Open the Chat view and switch the mode selector to **Agent**. Click the tools icon to confirm the Prowler tools are available, then ask: + +- *"Show me all critical findings from my AWS accounts"* +- *"What does the S3 bucket public access check do?"* +- *"Summarize my CIS compliance status by provider"* + + + VS Code Copilot Chat in agent mode showing the Prowler tools in the tools picker + + +Copilot asks for confirmation before running an MCP tool for the first time. + +## Troubleshooting + +### Server Does Not Appear + +- Confirm the root key is `servers`, not `mcpServers`. +- Confirm each server entry has `"type": "http"`. +- Check that `mcp.json` is valid JSON. +- Verify your VS Code version is 1.102 or later. + +### Authentication Fails With 401 + +- Verify the header value includes the `Bearer ` prefix. +- Confirm the key has not been revoked in Prowler Cloud. +- If you mistyped the key at the prompt, run **MCP: List Servers**, select `prowler`, and restart it to be prompted again. + +### Tools Do Not Appear in Chat + +- Make sure the Chat view is in **Agent** mode. MCP tools are not available in Ask mode. +- Open the tools picker and confirm the Prowler tools are enabled. + +## Next Steps + + + + Explore all available tools and capabilities + + + Configuration reference for every supported client + + + +## Getting Help + +- Search for existing [GitHub issues](https://github.com/prowler-cloud/prowler/issues) +- Ask for help in our [Slack community](https://goto.prowler.com/slack) +- Report a new issue on [GitHub](https://github.com/prowler-cloud/prowler/issues/new)