> ## Documentation Index
> Fetch the complete documentation index at: https://prowler-feat-codex-plugin.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Prowler product naming: Prowler App is now Prowler Local Server, and Prowler Enterprise is now Prowler Private Cloud. Always use the current names when answering. The full product reference is at /getting-started/products: Open Source projects are Prowler CLI, Prowler Local Server, Prowler Local Dashboard, and Prowler SDK; Prowler Products are Prowler Cloud, Prowler Private Cloud, Prowler Hub, Prowler Lighthouse AI, and Prowler MCP.

# Connect Codex / ChatGPT Desktop to Prowler MCP Server

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.

## Preferred Setup: Install the Prowler Plugin

The Prowler plugin is the recommended setup for Codex CLI. It adds Prowler Cloud security and compliance skills and configures the Prowler MCP Server with the required `User-Agent` header.

| Surface                         | Recommended Setup                                                                           | Notes                                                       |
| ------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| **Codex CLI**                   | Prowler plugin                                                                              | Reliably inherits the API key from the launching shell.     |
| **Codex / ChatGPT desktop app** | Plugin when supported, otherwise [manual MCP setup](#manual-mcp-setup-advanced-or-fallback) | May require configuring the application launch environment. |
| **Codex IDE extension**         | Plugin when supported, otherwise [manual MCP setup](#manual-mcp-setup-advanced-or-fallback) | May require configuring the IDE launch environment.         |
| **ChatGPT on the web**          | Not supported                                                                               | Does not read local Codex configuration.                    |

## Prerequisites

* **Codex CLI with plugin support.** Check with `codex --version` and `codex plugin --help`.
* **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 is shown only once. Check the [API Keys](/user-guide/tutorials/prowler-app-api-keys#creating-api-keys) guide for details.

## Step 2: Set the API Key Environment Variable

Export the key in the shell that launches Codex. Do not add a real key to a repository, shell history, or shared configuration file.

```bash theme={null}
export PROWLER_API_KEY="<your-Prowler-Cloud-API-key>"
```

`PROWLER_API_KEY` must contain the raw API key, without the `Bearer ` prefix. The plugin adds that prefix when it sends the `Authorization` header.

<Note>
  **Codex CLI reliably inherits this variable** when it starts from the shell where you exported it. Codex Desktop and IDE integrations may not inherit variables from your shell profile. Configure the desktop application or IDE launch environment with `PROWLER_API_KEY` when you use those surfaces.
</Note>

## Step 3: Install the Plugin

Add the Prowler marketplace, then install the Prowler plugin:

```bash theme={null}
codex plugin marketplace add prowler-cloud/prowler --ref master
codex plugin add prowler@prowler-plugins
```

The marketplace does not install Prowler by default. The `codex plugin add` command explicitly installs it.

## Step 4: Verify the Plugin

```bash theme={null}
codex plugin list --marketplace prowler-plugins
```

Start Codex from the same shell, then ask it to list your Prowler providers or to help triage a compliance framework.

## Manual MCP Setup: Advanced or Fallback

Use this setup only when the plugin is unavailable for your Codex surface or when you need a custom MCP configuration. The manual configuration must include the `User-Agent` header because Codex does not send one by default.

### Codex CLI

Register the server:

```bash theme={null}
codex mcp add prowler --url https://mcp.prowler.com/mcp
```

Then update `~/.codex/config.toml` because `codex mcp add` has no flag for the required header:

```toml theme={null}
[mcp_servers.prowler]
url = "https://mcp.prowler.com/mcp"
bearer_token_env_var = "PROWLER_API_KEY"
http_headers = { "User-Agent" = "codex" }
```

This manual CLI configuration uses the same secure environment-backed contract as the plugin: `PROWLER_API_KEY` holds the raw key, and Codex adds the `Bearer ` prefix.

### Codex / ChatGPT Desktop App

First configure `PROWLER_API_KEY` in the desktop application's launch environment. An API key exported only in a shell profile may not be available when the app starts from Finder, the Dock, or a launcher.

If you cannot configure the launch environment, add the server manually:

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 the `User-Agent` header with the value `codex`
6. If the app supports a reference to its launch environment, use `PROWLER_API_KEY`. Otherwise, add an `Authorization` header with `Bearer ` followed by the API key.

<Warning>
  A literal `Authorization` header stores the API key in plain text in `~/.codex/config.toml`. Use it only as a last resort, exclude the file from dotfile repositories and configuration sync, and revoke and re-issue the key if the file is shared.
</Warning>

Restart Codex after installing the plugin or changing the MCP configuration.

<Note>
  **Local server:** Replace the URL with your own HTTP endpoint. Keep the same authentication and `User-Agent` configuration.
</Note>

## Step 5: Verify the Connection

Run `/mcp` in the app or in a CLI session to list connected servers and their tools.

<Frame>
  <img src="https://mintcdn.com/prowler-feat-codex-plugin/mjLc2N-7TNLbBaSg/images/prowler-mcp/codex/codex-mcp-slash-command.png?fit=max&auto=format&n=mjLc2N-7TNLbBaSg&q=85&s=1c73c25e64469cdde712be462ae36aff" alt="Codex composer showing the /mcp command output with Prowler tools listed" width="1500" height="1336" data-path="images/prowler-mcp/codex/codex-mcp-slash-command.png" />
</Frame>

From the CLI you can also inspect the stored entry directly:

```bash theme={null}
codex mcp list          # one row per server, with status and auth
codex mcp get prowler   # full entry, header values masked
```

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

## Step 6: 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"*

<Frame>
  <img src="https://mintcdn.com/prowler-feat-codex-plugin/mjLc2N-7TNLbBaSg/images/prowler-mcp/codex/codex-prowler-query.png?fit=max&auto=format&n=mjLc2N-7TNLbBaSg&q=85&s=01db010848f065d4153995d7ec12c5ff" alt="Codex answering a question about critical findings using Prowler MCP tools" width="3446" height="2158" data-path="images/prowler-mcp/codex/codex-prowler-query.png" />
</Frame>

## 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: <html>
  <head><title>403 Forbidden</title></head>
```

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. The plugin adds this header automatically. For a manual configuration, add it as shown in [Manual MCP Setup](#manual-mcp-setup-advanced-or-fallback); the value itself does not matter, only that the header is present.

### Authentication Fails With 401

* For a manual configuration, run `codex mcp get prowler` and confirm the entry has the headers you expect. Values are masked, but a missing header shows as `-`.
* Verify the Codex process has `PROWLER_API_KEY` in its launch environment without printing the key: `test -n "$PROWLER_API_KEY" && echo "PROWLER_API_KEY is set"`.
* `PROWLER_API_KEY` must contain the raw key without `Bearer `. The plugin and the `bearer_token_env_var` manual configuration add the prefix automatically.
* If the CLI works but Codex Desktop or an IDE fails, configure `PROWLER_API_KEY` in that application's launch environment. Shell-profile exports may not be inherited. Use a literal `Authorization` header only as the last-resort desktop fallback described in [Manual MCP Setup](#manual-mcp-setup-advanced-or-fallback).
* 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 closing the window is not enough.

## Next Steps

<CardGroup cols={2}>
  <Card title="Tools Reference" icon="wrench" href="/getting-started/basic-usage/prowler-mcp-tools">
    Explore all available tools and capabilities
  </Card>

  <Card title="All MCP Clients" icon="plug" href="/getting-started/basic-usage/prowler-mcp">
    Configuration reference for every supported client
  </Card>
</CardGroup>

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