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

# Plerion MCP server

> Connect Claude, Claude Code, Cursor, VS Code, Windsurf, Zed, Kiro CLI, and Codex CLI to your Plerion tenant over the Model Context Protocol

With the **Plerion MCP server**, the AI client your team already uses can read and act on your Plerion tenant. The server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). It gives the client a tool for each [Public API](/api-reference/) operation, plus `pleri_chat` for questions in plain language. What the client can reach is limited to the permissions of whoever connected.

***

## How clients authenticate

The client determines which method applies.

| Method | Clients | Setup |
| - | - | - |
| **Sign in with Plerion (OAuth)** | Claude web, desktop, and mobile apps; Claude Code; Codex CLI | A Plerion organization administrator registers a connector once for the Claude apps. Claude Code and Codex CLI need no registration. |
| **API key** | Claude Code in CI, Codex CLI without a browser, Claude Desktop, Cursor, VS Code, Windsurf, Zed, Kiro CLI | Each user creates a tenant API key. |

With OAuth, each person signs in with their own Plerion account and chooses one tenant. The client acts as that person, with that person's permissions, in that tenant. With an API key, the client acts with the permissions of the key.

***

## Prerequisites

The MCP server URL is:

```text theme={"system"}
https://{region}.api.plerion.com/plerion/mcp
```

Replace `{region}` with the first part of the hostname you use for the Plerion dashboard. If you sign in at `https://au.app.plerion.com`, the region is `au`.

That URL is all you need for the Claude apps, Claude Code and Codex CLI. They sign in with your Plerion account, so none of them needs an API key.

The clients in the table above that use an API key need a tenant API key as well. Create one under [Settings > API Keys](https://app.plerion.com/settings/api-keys). Keys start with `plerion_tak_`.

<Warning>
  Treat the API key like a password. Do not commit it to source control or paste it into chat.
</Warning>

***

## Steps to connect the Claude apps

Setup happens once per organization, in two places. A **Plerion organization administrator** registers a connector in Plerion, and a **Claude Owner** adds it in Claude. After that, each person connects with their own Plerion account.

### Register the connector in Plerion

<Steps>
  <Step title="Go to Admin > Security > MCP connectors">
    Open [MCP connectors](https://app.plerion.com/admin/mcp-connectors) in the Plerion dashboard.
  </Step>

  <Step title="Click Register">
    The button is at the top right of the connector list.
  </Step>

  <Step title="Enter the connector details">
    * **Name:** A label for the connector, for example `Claude`.
    * **Redirect URI:** Leave the pre-filled value unchanged.

    Click `Register`.
  </Step>

  <Step title="Copy the client credentials">
    Copy the **Client ID**, the **Client secret**, and the **MCP server URL**. The secret is shown once. If you lose it, click `Rotate secret` on the connector to generate a new one.
  </Step>
</Steps>

<Note>
  Only organization administrators can register a connector. Users with organization read-only access can see the list but not register.

  The connector belongs to your Plerion organization. Users in other organizations cannot connect with it, even with the same client ID.
</Note>

### Add the connector in Claude

On Claude Team and Enterprise plans, a Claude Owner does this once for the whole Claude organization. On Pro and Max plans, each person does it for themselves. The two reach the dialog by different paths.

<Steps>
  <Step title="Open the custom connector dialog">
    * **Team and Enterprise:** go to `Organization settings` > `Connectors`, click `Add`, hover over `Custom`, and select `Web`.
    * **Pro and Max:** go to `Customize` > `Connectors`, click `+`, then `Add custom connector`.
  </Step>

  <Step title="Paste the MCP server URL">
    Use the **MCP server URL** copied from the Plerion connector.
  </Step>

  <Step title="Expand Advanced settings and paste the client credentials">
    Enter the **Client ID** and **Client secret** from the Plerion connector.
  </Step>

  <Step title="Click Add" />
</Steps>

<Warning>
  Claude treats the client credentials as optional, but Plerion requires them. Plerion does not support automatic client registration, so a connector added without a client ID and secret fails to connect and gives no error message.
</Warning>

### Connect as a user

<Steps>
  <Step title="Go to Customize > Connectors in Claude">
    Plerion is listed with a **Custom** label. If it is missing, quit Claude fully and reopen it.
  </Step>

  <Step title="Click Connect next to Plerion">
    A Plerion page opens. Sign in if asked, choose the tenant Claude may use, and click `Authorize`.
  </Step>

  <Step title="Turn the connector on in a chat">
    Back in Claude, open the **+** menu, choose **Connectors**, and switch Plerion on for that conversation.
  </Step>
</Steps>

<Note>
  One connection covers one tenant. To work in another tenant, disconnect in Claude and connect again, choosing the other tenant.
</Note>

***

## Connect other AI clients

<Tabs>
  <Tab title="Claude Code">
    Claude Code supports remote HTTP MCP servers and signs in with your own Plerion account. Nothing needs to be registered first.

    ```bash theme={"system"}
    claude mcp add --transport http plerion \
      https://{region}.api.plerion.com/plerion/mcp
    ```

    Run `/mcp` inside Claude Code, pick **plerion**, and authenticate. A browser opens on a Plerion page where you sign in and choose the tenant Claude Code may use. Claude Code identifies itself to Plerion with its own published metadata document, so there is no client ID or secret to paste.

    **With an API key**, for continuous integration (CI) or a machine without a browser:

    ```bash theme={"system"}
    claude mcp add --transport http plerion \
      https://{region}.api.plerion.com/plerion/mcp \
      --header "Authorization: Bearer plerion_tak_your_key_here"
    ```

    Or add it to the project's `.mcp.json` file. Create the file in the repository root if it does not exist:

    ```json theme={"system"}
    {
      "mcpServers": {
        "plerion": {
          "type": "http",
          "url": "https://{region}.api.plerion.com/plerion/mcp",
          "headers": {
            "Authorization": "Bearer plerion_tak_your_key_here"
          }
        }
      }
    }
    ```

    To make the server available in every project, use `~/.claude.json` with the same structure under `mcpServers`.

    <Tip>
      Run `claude mcp list` to confirm Plerion is connected, and `claude mcp get plerion` to inspect the configuration.
    </Tip>
  </Tab>

  <Tab title="Claude Desktop">
    Claude Desktop connects to remote MCP servers through `mcp-remote`, which requires Node.js.

    1. Open the configuration file:
       * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
       * Windows: `%APPDATA%\Claude\claude_desktop_config.json`
    2. Add the Plerion MCP server:

    ```json theme={"system"}
    {
      "mcpServers": {
        "plerion": {
          "command": "npx",
          "args": [
            "mcp-remote@latest",
            "https://{region}.api.plerion.com/plerion/mcp",
            "--header",
            "Authorization: Bearer ${PLERION_API_KEY}"
          ],
          "env": {
            "PLERION_API_KEY": "plerion_tak_your_key_here"
          }
        }
      }
    }
    ```

    3. Quit Claude Desktop fully and reopen it. It does not pick up configuration changes while running.

    Once connected, Plerion is listed under the MCP tools icon in Claude Desktop.
  </Tab>

  <Tab title="Cursor">
    Cursor has native HTTP MCP support.

    1. Open the MCP configuration:
       * Global: `~/.cursor/mcp.json`
       * Project-scoped: `.cursor/mcp.json` in the repository root
       * Or go to `Settings` > `Tools & Integrations` > `Add Custom MCP`.
    2. Add the Plerion MCP server:

    ```json theme={"system"}
    {
      "mcpServers": {
        "plerion": {
          "url": "https://{region}.api.plerion.com/plerion/mcp",
          "headers": {
            "Authorization": "Bearer ${PLERION_API_KEY}"
          },
          "env": {
            "PLERION_API_KEY": "plerion_tak_your_key_here"
          }
        }
      }
    }
    ```

    Cursor picks up configuration changes automatically. No restart is needed.
  </Tab>

  <Tab title="VS Code">
    Supported through **GitHub Copilot** (native HTTP) or the **Cline** extension.

    **GitHub Copilot:** open or create `.vscode/mcp.json` in the workspace.

    ```json theme={"system"}
    {
      "servers": {
        "plerion": {
          "type": "http",
          "url": "https://{region}.api.plerion.com/plerion/mcp",
          "headers": {
            "Authorization": "Bearer plerion_tak_your_key_here"
          }
        }
      }
    }
    ```

    **Cline:** open the Cline settings and add the server under **MCP Servers**.

    ```json theme={"system"}
    {
      "mcpServers": {
        "plerion": {
          "type": "streamableHttp",
          "url": "https://{region}.api.plerion.com/plerion/mcp",
          "headers": {
            "Authorization": "Bearer plerion_tak_your_key_here"
          }
        }
      }
    }
    ```

    <Tip>
      VS Code can discover MCP servers from Claude Desktop if you have already set it up there. Enable `chat.mcp.discovery.enabled` in the VS Code settings.
    </Tip>
  </Tab>

  <Tab title="Windsurf">
    1. Open the MCP configuration:
       * macOS: `~/.codeium/windsurf/mcp_config.json`
       * Windows: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
    2. Add the Plerion MCP server:

    ```json theme={"system"}
    {
      "mcpServers": {
        "plerion": {
          "serverUrl": "https://{region}.api.plerion.com/plerion/mcp",
          "headers": {
            "Authorization": "Bearer ${env:PLERION_API_KEY}"
          }
        }
      }
    }
    ```

    Set `PLERION_API_KEY` in your shell environment, or replace `${env:PLERION_API_KEY}` with the key itself.

    Windsurf restarts the context server after configuration changes. No editor restart is needed.
  </Tab>

  <Tab title="Zed">
    Zed uses `mcp-remote` as a bridge for HTTP servers, which requires Node.js.

    Open the Zed settings (`Cmd+,`) and add the server to `settings.json`:

    ```json theme={"system"}
    {
      "context_servers": {
        "plerion": {
          "source": "custom",
          "command": "npx",
          "args": [
            "-y",
            "mcp-remote",
            "https://{region}.api.plerion.com/plerion/mcp",
            "--header",
            "Authorization: Bearer ${PLERION_API_KEY}"
          ],
          "env": {
            "PLERION_API_KEY": "plerion_tak_your_key_here"
          }
        }
      }
    }
    ```

    Zed reloads settings automatically. No restart is needed.
  </Tab>

  <Tab title="Kiro CLI">
    Kiro CLI connects to remote MCP servers through `mcp-remote`, which requires Node.js.

    1. Open the MCP configuration file:
       * Global: `~/.kiro/settings/mcp.json`
       * Workspace-scoped: `.kiro/settings/mcp.json` in the repository root
    2. Add the Plerion MCP server:

    ```json theme={"system"}
    {
      "mcpServers": {
        "plerion": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://{region}.api.plerion.com/plerion/mcp",
            "--header",
            "Authorization: Bearer ${PLERION_API_KEY}"
          ],
          "env": {
            "PLERION_API_KEY": "plerion_tak_your_key_here"
          }
        }
      }
    }
    ```

    3. Set the API key. `mcp-remote` expands `${PLERION_API_KEY}` itself, so either keep it in the `env` block above or export it in your shell before launching Kiro CLI:

    ```bash theme={"system"}
    export PLERION_API_KEY="plerion_tak_your_key_here"
    ```

    **Native HTTP transport (alternative):** Kiro CLI can connect directly instead of through `mcp-remote`.

    ```json theme={"system"}
    {
      "mcpServers": {
        "plerion": {
          "type": "http",
          "url": "https://{region}.api.plerion.com/plerion/mcp",
          "headers": {
            "Authorization": "Bearer ${PLERION_API_KEY}",
            "User-Agent": "kiro-cli"
          }
        }
      }
    }
    ```

    <Warning>
      Kiro CLI's HTTP transport does not send a `User-Agent` header by default, and Plerion rejects requests without one. When using the HTTP transport, add a `User-Agent` header with any value, as shown above.
    </Warning>
  </Tab>

  <Tab title="Codex CLI">
    Codex signs in with your own Plerion account. Add the server, then log in:

    ```bash theme={"system"}
    codex mcp add plerion --url https://{region}.api.plerion.com/plerion/mcp

    codex mcp login plerion
    ```

    A browser opens for you to sign in and pick a tenant. Run `codex mcp list` to confirm: the `plerion` row shows `OAuth` under `Auth`. Nothing needs registering in Plerion first.

    The CLI, the ChatGPT desktop app and the IDE extension share `~/.codex/config.toml`, so logging in once covers all three.

    **API key (alternative):** on a machine with no browser, use a tenant API key instead.

    ```bash theme={"system"}
    codex mcp add plerion --url https://{region}.api.plerion.com/plerion/mcp \
      --bearer-token-env-var PLERION_API_KEY

    export PLERION_API_KEY="plerion_tak_your_key_here"
    ```

    Codex reads `PLERION_API_KEY` from the environment it is launched in, so export it in your shell profile if you want it to persist.

    <Warning>
      If a call fails with a 403 page from the CDN, Codex is not sending a `User-Agent` and Plerion rejects requests without one. Add one to the server's entry in `~/.codex/config.toml`:

      ```toml theme={"system"}
      [mcp_servers.plerion.http_headers]
      "User-Agent" = "codex"
      ```
    </Warning>
  </Tab>
</Tabs>

***

## What the client can do

### API tools

Each tool runs one [Public API](/api-reference/) operation: list alerts, get a finding, create an asset group. You ask in plain language and the client picks the tool, so the answer comes back as data rather than prose.

* "List the open critical findings in production."
* "Show me the asset groups in this tenant."
* "Which integrations are connected?"

Tools that change data are included, and they act as you. A tool that creates an asset group creates it in the tenant you connected, attributed to your account.

To see the tools your client was given, run `/mcp` in Claude Code, or open the connector under `Customize` > `Connectors` in the Claude apps.

<Note>
  **Two people can see different tools.** The list is built from the operations the connected account may call, so a tool you have no permission for never appears. If a colleague has a tool you do not, check with an administrator which roles your account holds.
</Note>

### pleri\_chat

Some questions span several operations, and some match none of them. `pleri_chat` passes those to Pleri, and the reply comes back as prose.

* "What are our top cloud security risks right now?"
* "Which workloads have exploitable vulnerabilities?"
* "What compliance gaps do we have for SOC 2?"
* "Which external accounts have access to our resources?"
* "Create a Jira ticket for finding F-12345."

Pleri covers findings, assets, access grants, compliance frameworks, workload vulnerabilities, code repositories, and the ticketing integrations. It also holds a conversation: the reply carries a conversation ID, and the client sends it back so follow-up questions keep the earlier context.

***

## Removing access

* **Your own connection:** In Plerion, go to [Profile > MCP connections](https://app.plerion.com/profile/mcp-connections) and click `Revoke` next to the app. The client loses access on its next request.
* **Everyone in the organization:** An administrator deletes the connector under `Admin` > `Security` > `MCP connectors`. Every connection made through it is revoked on its next request.
* **Rotating the secret:** `Rotate secret` keeps existing connections but stops them within about fifteen minutes, when their current tokens expire. Claude does not allow a connector's credentials to be edited, so the Claude Owner must remove the connector in Claude and add it again with the new secret. Everyone then connects again.
* **API key clients:** Delete the key under [Settings > API Keys](https://app.plerion.com/settings/api-keys). The client loses access on its next request.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.