# Bright MCP Integration

Bright's [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) integration brings **AI-powered application security testing** directly into your development workflow. Your AI coding assistant can discover API endpoints, run security scans, and review vulnerabilities — all through natural language conversation.

> **Bright MCP is a remote, cloud-hosted MCP server.** There is nothing to install locally — you simply point your MCP-compatible client at Bright's endpoint and authenticate with an API key.

## Quick Start

### 1. Get a Bright API Key

Create a dedicated API key in your Bright account. This can be a **personal**, **project**, or **organization-level** key with the relevant scopes. See [Personal API Key Scopes](https://docs.brightsec.com/docs/personal-api-key-scopes) for details.

### 2. Configure Your Client

Add Bright as a remote MCP server in your IDE or tool of choice. The server URL is:

```
https://app.brightsec.com/mcp
```

> **Note:** If your organization uses a dedicated Bright cluster, replace `app.brightsec.com` with your cluster's hostname.

See [Client Configuration](#client-configuration) below for IDE-specific instructions.

### 3. Start Using It

Ask your AI assistant something like:

```
Scan https://my-app.example.com for security vulnerabilities
```

Your assistant will use the Bright MCP tools to list projects, discover entrypoints, run scans, and report findings.

---

## Client Configuration

### VS Code (GitHub Copilot)

Add the following to your MCP configuration (via Command Palette → "MCP: Add Server" → Global, or manually edit your `mcp.json`):

```json
{
  "servers": {
    "brightsec.com": {
      "type": "sse",
      "url": "https://app.brightsec.com/mcp",
      "headers": {
        "Authorization": "Api-Key ${input:apiKey}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "Enter your Bright API Key",
      "password": true
    }
  ]
}
```

Then go to the **Extensions tab**, right-click the **brightsec.com** MCP server, and choose **Start Server**. You'll be prompted to enter your API key.

> Full guide: [Configure Bright MCP in VS Code](https://docs.brightsec.com/docs/configure-in-vscode)

### Augment Code

1. Open the **Augment Code** extension settings → **Tools** → **MCP**.
2. Click **+ Add remote MCP**.
3. Fill in:
   - **Connection Type:** HTTP
   - **Authentication Type:** Header
   - **Name:** BrightSec
   - **URL:** `https://app.brightsec.com/mcp`
   - **Header Name:** `Authorization`
   - **Header Value:** `Api-Key YOUR_API_KEY`
4. Click **Save**.

> Full guide: [Configure Bright MCP in Augment Code](https://docs.brightsec.com/docs/configure-bright-mcp-in-augment-code)

### Cursor

Add to your Cursor MCP settings (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "brightsec": {
      "url": "https://app.brightsec.com/mcp",
      "headers": {
        "Authorization": "Api-Key YOUR_API_KEY"
      }
    }
  }
}
```

### Windsurf

Add to your Windsurf MCP configuration (`~/.codeium/windsurf/mcp_config.json`):

```json
{
  "mcpServers": {
    "brightsec": {
      "serverUrl": "https://app.brightsec.com/mcp",
      "headers": {
        "Authorization": "Api-Key YOUR_API_KEY"
      }
    }
  }
}
```

### Generic MCP Client

Any MCP-compatible client that supports **remote HTTP/SSE servers** can connect to Bright. Configure it with:

| Setting         | Value                              |
| --------------- | ---------------------------------- |
| **Transport**   | SSE (Server-Sent Events) or HTTP   |
| **URL**         | `https://app.brightsec.com/mcp`    |
| **Auth Header** | `Authorization: Api-Key YOUR_KEY`  |

---

## Available Tools

Bright MCP exposes the following tools to your AI assistant:

### Project Management

| Tool | Description |
| ---- | ----------- |
| **listProjects** | List all projects accessible to your API key. Use this to find project IDs needed for other operations. |

### Endpoint Discovery

| Tool | Description |
| ---- | ----------- |
| **runDiscovery** | Discover API endpoints using crawling (`crawlerUrls`) or API definitions (`fileId` from `uploadApiDefinition`). Before running, check if the project already has entrypoints with `listEntrypoints`. For private/local targets, specify a connected repeater via `repeaters`. |
| **getDiscoveryStatus** | Get the current status of a discovery run. |
| **listDiscoveries** | List discovery history for a project. View past discovery runs or monitor ongoing endpoint discovery. |
| **uploadApiDefinition** | Upload an API definition file (OpenAPI/Swagger) by URL or content. Returns a file ID to reference in discovery runs. |

### Entrypoint Management

| Tool | Description |
| ---- | ----------- |
| **listEntrypoints** | List discovered API endpoints/URLs for a project. Use this to select entrypoints for scans or evaluate attack surface coverage. Supports filtering by HTTP method, status, and text search. |
| **getEntrypoint** | Get detailed information about a specific entrypoint by ID, including headers, body, and configuration. |
| **addEntrypoint** | Add a new entrypoint to a project. Entrypoints define HTTP requests (method, URL, headers, body) that can be used for security scanning. |
| **editEntrypoint** | Update an existing entrypoint. Modify the HTTP request definition, authentication, or repeater settings. |

### Security Scanning

| Tool | Description |
| ---- | ----------- |
| **runScan** | Start a security scan against selected entrypoints. Supports targeting specific entrypoints by ID or by status (e.g., `new`, `changed`, `vulnerable`). Configure which tests to run or use a scan template. For private/local targets, specify a connected repeater. |
| **getScanStatus** | Get the current status of a running scan. |
| **listScans** | List scan history for a project. View past scan results or check the status of multiple ongoing scans. |
| **listTests** | List all available security tests (e.g., SQL injection, XSS, CSRF) that can be included in scans. |

### Vulnerability Management

| Tool | Description |
| ---- | ----------- |
| **listIssues** | List security vulnerabilities found for a project. Filter by severity (`Low`, `Medium`, `High`, `Critical`), status (`new`, `recurring`, `resolved`, `ignored`), or entrypoint. |

### Authentication Configuration

| Tool | Description |
| ---- | ----------- |
| **listAuths** | List authentication configurations for a project. Use before scanning protected endpoints that require authentication. |
| **getAuth** | Get detailed information about a specific authentication configuration. |
| **addAuth** | Create a new authentication configuration. Supports multiple auth types: static headers, OAuth 2.0/OIDC, multi-step HTTP flows, NTLM, browser-based login, and recorded browser flows. |
| **editAuth** | Update an existing authentication configuration. |

### Private/Local Target Access

| Tool | Description |
| ---- | ----------- |
| **createRepeater** | Create a repeater for accessing private/local targets. After creation, run the Bright CLI to start the repeater and establish the connection. |
| **listRepeaters** | List repeaters and their connection status. Verify a repeater is connected before scanning non-public applications. |

---

## Usage Examples

### Scan a Public Application

> "Scan https://my-app.example.com for security vulnerabilities"

The assistant will:
1. List your projects to find the appropriate one
2. Get all discovered entrypoints for the project
3. Run a security scan against those entrypoints
4. Monitor the scan status and report findings

### Discover Endpoints from an OpenAPI Spec

> "Discover API endpoints from the OpenAPI spec at https://my-app.example.com/openapi.json"

The assistant will:
1. Upload the OpenAPI definition file
2. Run file-based discovery
3. Monitor the discovery status

### Scan a Local/Private Application

> "Scan my local application at http://localhost:3000"

The assistant will:
1. Check if Bright CLI is installed for repeater connectivity
2. List your projects to find the appropriate one
3. Create a repeater if needed
4. Run a security scan through the repeater
5. Monitor the scan status and report findings

### Check for Critical Vulnerabilities

> "Show me all critical and high severity issues in my project"

The assistant will:
1. List your projects
2. Query issues filtered by `Critical` and `High` severity
3. Present findings with details

### Scan with Authentication

> "Scan my API that requires Bearer token authentication"

The assistant will:
1. Create or find an existing auth configuration
2. Set up the proper headers/token flow
3. Run the scan with authentication applied

See the [`examples/`](./examples/) directory for more detailed workflow examples.

---

## How It Works

```
┌─────────────────────┐         ┌──────────────────────┐
│   AI Assistant       │  MCP    │   Bright Cloud       │
│   (VS Code, Cursor,  │◄──────►│   (app.brightsec.com)│
│    Windsurf, etc.)   │  SSE    │                      │
└─────────────────────┘         └──────────┬───────────┘
                                           │
                                           │ Scans
                                           ▼
                                ┌──────────────────────┐
                                │   Your Application   │
                                │   (public or via      │
                                │    repeater)          │
                                └──────────────────────┘
```

1. **Your AI assistant** connects to Bright's MCP endpoint over SSE/HTTP.
2. **Bright's cloud platform** receives tool calls and orchestrates security operations.
3. **Scans run against your application** — either directly (public targets) or through a **Repeater** (private/local targets).

---

## Repeaters (Private/Local Targets)

To scan applications that aren't publicly accessible, Bright uses **Repeaters** — lightweight agents that route scan traffic from Bright's cloud through your local network.

1. Create a repeater via the MCP tool (`createRepeater`)
2. Start the repeater using the Bright CLI:
   ```bash
   bright-cli repeater \
     --id <REPEATER_ID> \
     --hostname app.brightsec.com \
     --token <YOUR_API_KEY>
   ```
3. Reference the repeater when running scans or discoveries

> See the [Bright CLI Installation Guide](https://docs.brightsec.com/docs/cli-installation-guide) for setup instructions.

---

## Resources

- [Bright Documentation](https://docs.brightsec.com/)
- [Bright MCP Tools Reference](https://docs.brightsec.com/docs/bright-mcp-tools)
- [VS Code Configuration Guide](https://docs.brightsec.com/docs/configure-in-vscode)
- [Augment Code Configuration Guide](https://docs.brightsec.com/docs/configure-bright-mcp-in-augment-code)
- [API Key Scopes](https://docs.brightsec.com/docs/personal-api-key-scopes)
- [Bright CLI Installation](https://docs.brightsec.com/docs/cli-installation-guide)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)

---

## License

This repository contains configuration examples and documentation for Bright's MCP integration. Bright's security scanning platform is a commercial SaaS product — visit [brightsec.com](https://brightsec.com) for more information.