Installation

Prerequisites

Before installing the plugin for any tool, make sure you have:

1. A Bright API token — create one in Bright under Organization → API Keys or Project → API Keys. See Personal API Key Scopes.
2. Your Bright cluster hostname — typically app.brightsec.com (EU cluster: eu.brightsec.com).

Export both as environment variables so the plugin and the Bright Repeater can read them:

export BRIGHT_HOSTNAME="app.brightsec.com"
export BRIGHT_TOKEN="your-bright-api-token"

📘

Persist these in your shell profile (~/.zshrc, ~/.bashrc) so every session has them.

Install for your tool

Each tool has its own native install steps. Follow the README for your tool:

All packages use the same Bright MCP server under the hood — the differences are tool-specific plugin mechanics, frontmatter, and how the MCP server gets registered.

Register the Bright MCP server

The plugin ships agents and skills. Those are the instructions; the Bright tools come from the MCP server. For Cursor, Claude Code, and Devin the package bundles an MCP config and there is nothing more to do. For Codex, Copilot CLI, and Antigravity the tool loads MCP servers from its own configuration, so the server has to be registered once — otherwise the agents install correctly and then have nothing to call.

⚠️

Skipping this step is the most common cause of "the plugin is installed but Bright tools don't appear."

Codex

codex mcp add brightsec --url "https://$BRIGHT_HOSTNAME/mcp" --bearer-token-env-var BRIGHT_TOKEN

Verify with codex mcp list — brightsec should be enabled with BRIGHT_TOKEN as its bearer-token env var. Codex doesn't interpolate ${VAR} in MCP config files, which is why the token is passed as an env-var name rather than a value.

GitHub Copilot CLI

copilot mcp add --transport http --header "Authorization: Api-Key $BRIGHT_TOKEN" \
  brightsec "https://$BRIGHT_HOSTNAME/mcp"

Verify with copilot mcp get brightsec — it should show brightsec enabled, over http, with the Authorization header.

Antigravity CLI

Antigravity reads MCP servers from ~/.gemini/config/mcp_config.json. Add the server there, using serverUrl rather than url:

{
  "mcpServers": {
    "brightsec": {
      "serverUrl": "https://app.brightsec.com/mcp",
      "headers": {
        "Authorization": "Api-Key <your-bright-api-token>"
      }
    }
  }
}

Use literal values here. The mcp_config.json bundled with the package ships ${BRIGHT_HOSTNAME} / ${BRIGHT_TOKEN} placeholders as a template, because env-var expansion in this file isn't guaranteed across Antigravity versions.

GitHub Copilot coding agent

This surface is configured differently again: the agent definitions in .github/agents/ carry their own mcp-servers block, so no command is needed, but the credentials come from the repository rather than your shell. Set BRIGHT_TOKEN as a secret and BRIGHT_HOSTNAME as a variable in the repository's copilot environment, and allowlist your Bright host so the agent can reach it. See the package README for the exact steps.

For a self-hosted or non-default cluster, point the URL at your own host in whichever method applies — all three commands above already read it from BRIGHT_HOSTNAME.

Verify the installation

After installing — and, where required, registering the MCP server — confirm:

1. The Bright MCP server (brightsec) is connected and active in your tool's MCP settings, and Bright tools are listed. Agents present with no tools behind them means the MCP server isn't registered.
2. The Bright agents appear in the agent list (or as available skills, depending on the tool) — see Agents & Skills for what to expect.
3. Environment variables are accessible — run echo $BRIGHT_HOSTNAME and echo $BRIGHT_TOKEN in the same shell.

📘

Export the variables before launching the tool. Most tools read MCP configuration at startup, so a variable exported mid-session never reaches the already-registered server. The agents check both up front and stop with a message naming what's missing rather than failing later as an authentication error.

Update & uninstall

Each package README includes tool-specific update and uninstall instructions. The general pattern:

• Update: refresh the marketplace catalog, then update the plugin (or git pull for clone-based setups).
• Uninstall: disable or remove the plugin from the tool's settings, then optionally remove the marketplace source.

See the per-tool README linked above for exact commands.

Troubleshooting

For deeper troubleshooting, see the Advanced usage section in each tool's README.