Plerion MCP server

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). It gives the client a tool for each Public API 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:

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. Keys start with plerion_tak_.

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

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

Go to Admin > Security > MCP connectors

Open MCP connectors in the Plerion dashboard.

Click Register

The button is at the top right of the connector list.

Enter the connector details

Name: A label for the connector, for example Claude.
Redirect URI: Leave the pre-filled value unchanged.

Click Register.

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.

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.

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.

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.

Paste the MCP server URL

Use the MCP server URL copied from the Plerion connector.

Expand Advanced settings and paste the client credentials

Enter the Client ID and Client secret from the Plerion connector.

Click Add

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.

Connect as a user

Go to Customize > Connectors in Claude

Plerion is listed with a Custom label. If it is missing, quit Claude fully and reopen it.

Click Connect next to Plerion

A Plerion page opens. Sign in if asked, choose the tenant Claude may use, and click Authorize.

Turn the connector on in a chat

Back in Claude, open the + menu, choose Connectors, and switch Plerion on for that conversation.

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

Connect other AI clients

Claude Code supports remote HTTP MCP servers and signs in with your own Plerion account. Nothing needs to be registered first.

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:

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:

{
  "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.

Run claude mcp list to confirm Plerion is connected, and claude mcp get plerion to inspect the configuration.

Claude Desktop connects to remote MCP servers through mcp-remote, which requires Node.js.

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

{
  "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"
      }
    }
  }
}

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.

Cursor has native HTTP MCP support.

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.
Add the Plerion MCP server:

{
  "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.

Supported through GitHub Copilot (native HTTP) or the Cline extension.GitHub Copilot: open or create .vscode/mcp.json in the workspace.

{
  "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.

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

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.

Open the MCP configuration:
- macOS: ~/.codeium/windsurf/mcp_config.json
- Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
Add the Plerion MCP server:

{
  "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.

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:

{
  "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.

Kiro CLI connects to remote MCP servers through mcp-remote, which requires Node.js.

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

{
  "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"
      }
    }
  }
}

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:

export PLERION_API_KEY="plerion_tak_your_key_here"

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

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

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.

Codex signs in with your own Plerion account. Add the server, then log in:

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.

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.

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:

[mcp_servers.plerion.http_headers]
"User-Agent" = "codex"

What the client can do

API tools

Each tool runs one Public API 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.

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.

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 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. The client loses access on its next request.

Getting started

Administration

Integrations

Platform

How clients authenticate

Prerequisites

Steps to connect the Claude apps

Register the connector in Plerion

Add the connector in Claude

Connect as a user

Connect other AI clients

What the client can do

API tools

pleri_chat

Removing access

​How clients authenticate

​Prerequisites

​Steps to connect the Claude apps

​Register the connector in Plerion

​Add the connector in Claude

​Connect as a user

​Connect other AI clients

​What the client can do

​API tools

​pleri_chat

​Removing access

How clients authenticate

Prerequisites

Steps to connect the Claude apps

Register the connector in Plerion

Add the connector in Claude

Connect as a user

Connect other AI clients

What the client can do

API tools

pleri_chat

Removing access