Skip to main content
Glama
InsightAppSec MCP Server

InsightAppSec MCP Server

by wagonbomb

InsightAppSec MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to the Rapid7 InsightAppSec API for application security scanning, vulnerability management, and reporting.

Overview

This MCP server enables AI assistants like Claude to interact with Rapid7 InsightAppSec, allowing you to:

  • Manage applications and their security configurations

  • Launch and monitor security scans

  • Query and triage vulnerabilities

  • Generate security reports

  • Automate scan scheduling

  • Search across all InsightAppSec resources

  • Configure authentication (OAuth, form-based, macros, traffic files)

  • Manage token replacement (CSRF, session tokens, dynamic parameters)

Related MCP server: Intigriti MCP Server

Prerequisites

Installation

From Source

# Clone the repository
git clone https://github.com/yourusername/insightappsec-mcp.git
cd insightappsec-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Create a .env file based on the provided template:

cp .env.example .env

Edit the .env file with your credentials:

INSIGHTAPPSEC_API_KEY=your-api-key-here
INSIGHTAPPSEC_REGION=us

Supported Regions:

Region

Code

United States

us

Europe

eu

Asia-Pacific

ap

Canada

ca

Australia

au

Usage with Claude Desktop

Add the following to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "insightappsec": {
      "command": "node",
      "args": ["C:/path/to/insightappsec-mcp/build/index.js"],
      "env": {
        "INSIGHTAPPSEC_API_KEY": "your-api-key-here",
        "INSIGHTAPPSEC_REGION": "us"
      }
    }
  }
}

Restart Claude Desktop to load the MCP server.

Available Tools

Application Management

Tool

Description

list_apps

List all applications with pagination and sorting

get_app

Get detailed information about a specific application

create_app

Create a new application

update_app

Update application name or description

delete_app

Delete an application and all associated data

manage_app_tags

Add or remove tags from an application

Scan Operations

Tool

Description

list_scans

List scans with pagination and filtering

get_scan

Get detailed information about a specific scan

submit_scan

Submit a new scan based on a scan configuration

delete_scan

Delete a failed scan

control_scan

Pause, resume, stop, or cancel a running scan

get_scan_execution_details

Get real-time execution metrics for a scan

get_scan_engine_events

Get engine event logs for a scan

Scan Configuration

Tool

Description

list_scan_configs

List all scan configurations

get_scan_config

Get details of a specific scan configuration

create_scan_config

Create a new scan configuration

update_scan_config

Update scan configuration settings

delete_scan_config

Delete a scan configuration

Vulnerability Management

Tool

Description

list_vulnerabilities

List vulnerabilities with pagination and sorting

get_vulnerability

Get detailed information about a vulnerability

update_vulnerability

Update vulnerability status or severity

get_vulnerability_discoveries

Get discovery history for a vulnerability

list_vulnerability_comments

List all comments on a vulnerability

add_vulnerability_comment

Add a comment to a vulnerability

Scheduling & Automation

Tool

Description

list_schedules

List all scan schedules

get_schedule

Get details of a specific schedule

create_schedule

Create a recurring scan schedule

update_schedule

Update schedule frequency or timing

delete_schedule

Delete a scan schedule

Blackout Windows

Tool

Description

list_blackouts

List all blackout windows

get_blackout

Get details of a specific blackout window

create_blackout

Create a blackout window to prevent scans

update_blackout

Update blackout window settings

delete_blackout

Delete a blackout window

Reporting

Tool

Description

list_reports

List all generated reports

generate_report

Generate a new vulnerability report

get_report_status

Check the status of a report generation

Tool

Description

search

Universal search across all InsightAppSec resources using DSL query syntax

Infrastructure

Tool

Description

list_engines

List all registered scan engines

get_engine

Get details of a specific scan engine

list_engine_groups

List all engine groups

get_engine_group

Get details of a specific engine group

File Management

Tool

Description

list_files

List all files for an application (macros, traffic, selenium, etc.)

get_file

Get file metadata by ID

create_file

Create file metadata entry

upload_file_content

Upload binary file content (base64-encoded)

delete_file

Delete a file

download_file

Download file content as base64

Supported File Types:

  • MACRO - Recorded authentication sequences (.rec)

  • RECORDED_TRAFFIC - HTTP traffic captures (.har, .trec, .saz)

  • SELENIUM - Browser automation scripts (.html, .side)

  • CERTIFICATE - SSL certificates (.pfx)

  • SWAGGER - API specifications (.json, .yaml)

  • WSDL - Web service definitions (.wsdl)

  • GRAPHQL - GraphQL schemas (.graphqls)

Authentication & Token Management

Tool

Description

get_scan_config_options

Get full scan config options including auth settings

configure_form_auth

Configure form-based authentication (username/password)

configure_oauth

Configure OAuth 2.0 authentication

configure_token_replacement

Configure global token extraction/injection rules

configure_session_handling

Configure session detection, cookies, relogin triggers

configure_csrf_handling

Configure automatic CSRF token detection and injection

configure_macro_auth

Link a macro file to scan config for authentication

configure_traffic_auth

Link a traffic file to scan config for authentication

Example Conversations

List Applications

"Show me all my applications in InsightAppSec"

The assistant will use list_apps to retrieve and display your applications.

Start a Security Scan

"Start a scan using the 'Production Web App' scan configuration"

The assistant will:

  1. Use list_scan_configs to find the configuration

  2. Use submit_scan to start the scan

  3. Report the scan ID and status

Check Vulnerability Status

"Show me all high severity vulnerabilities"

The assistant will use search with a DSL query:

type: VULNERABILITY
query: vulnerability.severity='HIGH'

Monitor a Running Scan

"What's the status of scan abc-123?"

The assistant will use get_scan and get_scan_execution_details to show:

  • Current scan status

  • Progress percentage

  • Requests completed

  • Vulnerabilities found so far

Triage Vulnerabilities

"Mark vulnerability xyz-789 as a false positive and add a comment explaining why"

The assistant will:

  1. Use update_vulnerability to set status to FALSE_POSITIVE

  2. Use add_vulnerability_comment to add the explanation

Schedule Recurring Scans

"Set up a weekly scan for the production app every Monday at 2 AM"

The assistant will use create_schedule with:

  • Frequency: WEEKLY

  • Start time: Next Monday at 2:00 AM UTC

Configure OAuth Authentication

"Set up OAuth client credentials authentication for the API scan"

The assistant will use configure_oauth with:

  • Grant type: CLIENT_CREDENTIALS

  • Token URL, client ID, client secret

Set Up Token Replacement for CSRF

"Configure the scan to automatically handle CSRF tokens"

The assistant will use configure_csrf_handling with:

  • auto_detect: true

  • Optional regex patterns for token names

Upload Authentication Macro

"Upload my recorded login macro for the scan"

The assistant will:

  1. Use create_file to create metadata (type: MACRO)

  2. Use upload_file_content with base64-encoded macro content

  3. Use configure_macro_auth to link it to the scan config

Search Query Syntax

The search tool supports a powerful DSL for querying resources:

Operators

Operator

Description

Example

=

Equals

vulnerability.severity='HIGH'

!=

Not equals

scan.status!='COMPLETE'

>, <, >=, <=

Comparison

vulnerability.cvss>7.0

CONTAINS

Substring match

app.name CONTAINS 'prod'

IN

Value in list

vulnerability.status IN ['UNREVIEWED', 'VERIFIED']

AND, OR

Logical operators

severity='HIGH' AND status='UNREVIEWED'

Searchable Resource Types

  • VULNERABILITY

  • SCAN

  • SCAN_CONFIG

  • APP

  • SCHEDULE

  • BLACKOUT

  • MODULE

  • ATTACK_TEMPLATE

  • ENGINE

  • ENGINE_GROUP

Example Queries

# Find critical vulnerabilities in production apps
type: VULNERABILITY
query: vulnerability.severity='HIGH' AND app.name CONTAINS 'prod'

# Find running scans
type: SCAN
query: scan.status='RUNNING'

# Find scan configs without recent scans
type: SCAN_CONFIG
query: scan_config.last_scan_date < '2024-01-01'

Authentication Configuration

The MCP server supports comprehensive authentication configuration for scanning authenticated applications.

OAuth 2.0 Authentication

Configure OAuth for API-based authentication:

configure_oauth:
  scan_config_id: "uuid"
  grant_type: "CLIENT_CREDENTIALS"
  token_url: "https://auth.example.com/oauth/token"
  client_id: "your-client-id"
  client_secret: "your-client-secret"
  scope: "read write"

Supported grant types:

  • CLIENT_CREDENTIALS - Server-to-server authentication

  • AUTHORIZATION_CODE - User-delegated access

  • RESOURCE_OWNER_PASSWORD - Direct username/password

  • IMPLICIT - Browser-based apps

Form-Based Authentication

Configure traditional login form authentication:

configure_form_auth:
  scan_config_id: "uuid"
  username_field: "email"
  password_field: "password"
  username: "test@example.com"
  password: "testpassword"
  logged_in_regex: "Welcome|Dashboard"
  logout_link_regex: "logout|sign.out"

Token Replacement

Extract tokens from responses and inject them into subsequent requests:

configure_token_replacement:
  scan_config_id: "uuid"
  extraction_location: "RESPONSE_BODY"
  extraction_pattern: "csrf_token\":\"([^\"]+)\""
  injection_location: "REQUEST_HEADER"
  injection_parameter: "X-CSRF-Token"

Supported locations:

  • REQUEST_URL, REQUEST_HEADER, REQUEST_BODY, REQUEST_COOKIE

  • RESPONSE_HEADER, RESPONSE_BODY

CSRF Token Handling

Enable automatic CSRF token detection and injection:

configure_csrf_handling:
  scan_config_id: "uuid"
  auto_detect: true
  token_name_regex: "csrf|_token|authenticity"

Session Management

Configure session detection and automatic re-authentication:

configure_session_handling:
  scan_config_id: "uuid"
  session_cookie_regex: "JSESSIONID|PHPSESSID"
  session_loss_regex: "session expired|please login"
  relogin_on_session_loss: true
  lock_cookies: true

Macro-Based Authentication

Use recorded macros for complex authentication flows:

  1. Upload the macro file:

create_file:
  app_id: "uuid"
  name: "login-macro.rec"
  type: "MACRO"

upload_file_content:
  app_id: "uuid"
  file_id: "uuid"
  content_base64: "<base64-encoded-macro>"
  1. Configure the scan to use it:

configure_macro_auth:
  scan_config_id: "uuid"
  macro_file_id: "uuid"
  replay_speed: 1.0

Vulnerability Statuses

Status

Description

UNREVIEWED

New vulnerability, not yet triaged

FALSE_POSITIVE

Determined to be a false positive

VERIFIED

Confirmed as a real vulnerability

IGNORED

Acknowledged but accepted risk

REMEDIATED

Fixed in the application

DUPLICATE

Duplicate of another finding

Severity Levels

Severity

Description

SAFE

No security impact

INFORMATIONAL

Information disclosure

LOW

Minor security concern

MEDIUM

Moderate security risk

HIGH

Serious security vulnerability

Development

Project Structure

insightappsec-mcp/
├── src/
│   ├── index.ts              # Entry point
│   ├── config.ts             # Configuration management
│   ├── client/
│   │   └── api-client.ts     # HTTP client for InsightAppSec API
│   ├── schemas/
│   │   └── common.ts         # Shared Zod schemas
│   ├── tools/
│   │   ├── apps.ts           # Application management tools
│   │   ├── scans.ts          # Scan operation tools
│   │   ├── scan-configs.ts   # Scan configuration tools
│   │   ├── vulnerabilities.ts # Vulnerability management tools
│   │   ├── schedules.ts      # Schedule management tools
│   │   ├── blackouts.ts      # Blackout window tools
│   │   ├── engines.ts        # Engine management tools
│   │   ├── reports.ts        # Reporting tools
│   │   ├── search.ts         # Search tool
│   │   ├── files.ts          # File management tools
│   │   └── auth.ts           # Authentication configuration tools
│   └── utils/
│       └── response-formatter.ts  # MCP response formatting
├── build/                    # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── .env.example

Scripts

# Build the project
npm run build

# Run in development mode
npm run dev

# Type checking
npm run typecheck

# Run tests
npm test

Adding New Tools

  1. Create or modify a tool file in src/tools/

  2. Use the server.tool() method to register the tool:

server.tool(
  "tool_name",
  "Tool description",
  {
    param1: z.string().describe("Parameter description"),
    param2: z.number().optional().describe("Optional parameter"),
  },
  async ({ param1, param2 }) => {
    const result = await client.get<unknown>("/endpoint");

    if (result.error) {
      return formatErrorResponse(result.error);
    }

    return formatResponse(result.data);
  }
);
  1. Import and register in src/index.ts

Error Handling

The server handles common API errors gracefully:

Status Code

Meaning

400

Bad request - check parameters

401

Authentication failed - check API key

403

Access forbidden - insufficient permissions

404

Resource not found

409

Resource conflict

422

Validation error - check request body

429

Rate limited - wait and retry

5xx

Server error - retry later

Error responses include:

  • Status code

  • Error message

  • Correlation ID (for Rapid7 support)

  • Detailed error information when available

API Reference

This MCP server wraps the Rapid7 InsightAppSec API v1.

For detailed API documentation, see:

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Support

  • For InsightAppSec API issues, contact Rapid7 Support

  • For MCP server issues, open a GitHub issue

Available Tools

56 tools
add_vulnerability_commentC

Add a comment to a vulnerability

Inputs: content (required), vulnerability_id (required).

configure_csrf_handlingC

Configure automatic CSRF token detection and injection

Inputs: auto_detect (required), scan_config_id (required), token_name_regex, token_value_regex.

configure_form_authB

Configure form-based authentication (username/password login) for a scan configuration

Inputs: password (required), username (required), password_field (required), scan_config_id (required), +4 more.

configure_macro_authC

Configure macro-based authentication using a previously uploaded macro file

Inputs: macro_file_id (required), scan_config_id (required), replay_speed, extra_delay_ms.

configure_oauthB

Configure OAuth 2.0 authentication for a scan configuration

Inputs: client_id (required), token_url (required), grant_type (required), client_secret (required), +6 more.

configure_session_handlingC

Configure session management including cookie handling and automatic re-login on session loss

Inputs: scan_config_id (required), lock_cookies, session_loss_regex, session_cookie_regex, +2 more.

configure_token_replacementA

Configure global token replacement rules to extract tokens from responses and inject them into subsequent requests.

Use this for dynamic tokens like CSRF tokens, API keys, or session identifiers that need to be captured and replayed.

Inputs: scan_config_id (required), extraction_pattern (required), injection_location (required), extraction_location (required), +2 more.

configure_traffic_authA

Configure traffic-based authentication using a previously uploaded traffic file (.har, .trec, .saz)

Inputs: scan_config_id (required), traffic_file_id (required), traffic_file_password.

control_scanB

Control a running scan (pause, resume, stop, or cancel)

Inputs: action (required), scan_id (required).

create_appC

Create a new application

Inputs: name (required), description.

create_blackoutA

Create a blackout window to prevent scans during maintenance periods

Inputs: name (required), stop (required), start (required), enabled, +1 more.

create_fileA

Create file metadata entry. After creating, use upload_file_content to upload the actual file.

Supported file types:

  • MACRO: Recorded authentication sequences (.rec)

  • RECORDED_TRAFFIC: HTTP traffic captures (.har, .trec, .saz)

  • SELENIUM: Browser automation scripts (.html, .side)

  • CERTIFICATE: SSL certificates (.pfx)

  • SWAGGER: API specifications (.json, .yaml)

  • WSDL: Web service definitions (.wsdl)

  • GRAPHQL: GraphQL schemas (.graphqls)

Inputs: name (required), type (required), app_id (required), description.

create_scan_configA

Create a new scan configuration for an application

Inputs: name (required), app_id (required), attack_template_id (required), description.

create_scheduleB

Create a new scan schedule for automated recurring scans

Inputs: frequency (required), first_start (required), scan_config_id (required), enabled.

delete_appA

Delete an application. This will also delete all associated scan configs, scans, and vulnerabilities.

Inputs: app_id (required).

delete_blackoutB

Delete a blackout window

Inputs: blackout_id (required).

delete_fileB

Delete a file from an application

Inputs: app_id (required), file_id (required).

delete_scanA

Delete a scan. Only scans in FAILED status can be deleted.

Inputs: scan_id (required).

delete_scan_configB

Delete a scan configuration

Inputs: scan_config_id (required).

delete_scheduleB

Delete a scan schedule

Inputs: schedule_id (required).

download_fileB

Download file content as base64-encoded string

Inputs: app_id (required), file_id (required).

generate_reportB

Generate a new vulnerability report for an application or scan

Inputs: name (required), report_type (required), app_id, format, +1 more.

get_appB

Get detailed information about a specific application

Inputs: app_id (required).

get_blackoutA

Get detailed information about a specific blackout window

Inputs: blackout_id (required).

get_engineA

Get detailed information about a specific scan engine

Inputs: engine_id (required).

get_engine_groupB

Get detailed information about a specific engine group

Inputs: engine_group_id (required).

get_fileA

Get file metadata by ID

Inputs: app_id (required), file_id (required).

get_report_statusB

Get the status and details of a generated report

Inputs: report_id (required).

get_scanB

Get detailed information about a specific scan

Inputs: scan_id (required).

get_scan_configB

Get detailed information about a specific scan configuration

Inputs: scan_config_id (required).

get_scan_config_optionsB

Get the full scan configuration options including authentication settings

Inputs: scan_config_id (required).

get_scan_engine_eventsA

Get engine event logs for a scan

Inputs: scan_id (required), size, index.

get_scan_execution_detailsA

Get real-time execution metrics for a running or completed scan

Inputs: scan_id (required).

get_scheduleA

Get detailed information about a specific schedule

Inputs: schedule_id (required).

get_vulnerabilityA

Get detailed information about a specific vulnerability

Inputs: vulnerability_id (required).

get_vulnerability_discoveriesB

Get the discovery history for a vulnerability

Inputs: vulnerability_id (required), size, index.

list_appsA

List all applications with optional pagination and sorting

Inputs: size, sort, index.

list_blackoutsB

List blackout windows with optional pagination

Inputs: size, index.

list_engine_groupsB

List engine groups with optional pagination

Inputs: size, index.

list_enginesB

List registered scan engines with optional pagination

Inputs: size, index.

list_filesA

List all files for an application (macros, traffic files, selenium scripts, etc.)

Inputs: app_id (required), size, index.

list_reportsC

List generated reports with optional pagination

Inputs: size, index.

list_scan_configsB

List scan configurations with optional pagination

Inputs: size, sort, index.

list_scansB

List scans with optional pagination, sorting, and filtering

Inputs: size, sort, index.

list_schedulesA

List scan schedules with optional pagination

Inputs: size, index.

list_vulnerabilitiesC

List vulnerabilities with optional pagination, sorting, and filtering

Inputs: size, sort, index.

list_vulnerability_commentsA

List all comments on a vulnerability

Inputs: vulnerability_id (required).

manage_app_tagsB

Add or remove tags from an application

Inputs: action (required), app_id (required), tag_id (required).

submit_scanA

Submit a new scan based on a scan configuration

Inputs: scan_config_id (required).

update_appA

Update an existing application

Inputs: app_id (required), name, description.

update_blackoutC

Update an existing blackout window

Inputs: blackout_id (required), name, stop, start, +1 more.

update_scan_configC

Update an existing scan configuration

Inputs: scan_config_id (required), name, description.

update_scheduleB

Update an existing scan schedule

Inputs: schedule_id (required), enabled, frequency, first_start.

update_vulnerabilityA

Update the status or severity of a vulnerability

Inputs: vulnerability_id (required), status, severity.

upload_file_contentA

Upload binary file content. The file metadata must be created first using create_file.

Inputs: app_id (required), file_id (required), content_base64 (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 56 tools

    Disambiguation4/5

    Most tools are clearly distinct by resource and action, such as list_apps vs create_app. However, the several scan-related getters (get_scan, get_scan_execution_details, get_scan_engine_events) could cause confusion, and the universal search tool overlaps with list functions.

    Naming Consistency4/5

    The vast majority follow the verb_noun pattern with snake_case, e.g., list_schedules, create_scan_config. Minor deviations like manage_app_tags and control_scan, while still understandable, break the otherwise consistent CRUD-oriented naming.

    Tool Count2/5

    With 56 tools, this far exceeds the recommended range of 3-15 and even the borderline 16-25. While the API scope is broad, many tools could be consolidated (e.g., all configure_* authentication tools), making the set feel oversized and harder to navigate.

    Completeness5/5

    The tool set provides thorough lifecycle coverage across multiple domains: applications, scans, scan configurations, vulnerabilities, schedules, blackouts, files, reports, and auth settings. CRUD operations are consistently present, and even edge cases like scan control and file uploads are included, leaving no major gaps.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Provides a Model Context Protocol server implementation that allows AI agents and other MCP clients to programmatically interact with DefectDojo, a vulnerability management tool, for managing findings, products, and engagements.
      11
      57 PyPI
      21
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server for interacting with the Intigriti bug bounty platform's Researcher API. It enables AI assistants to manage bug bounty programs, submissions, and research workflow.
      8
      4
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A remote MCP server that exposes mock application security testing data (applications, scans, issues) for LLM clients to query security posture using natural language.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      A unified MCP server for Rapid7's security platform, exposing InsightVM (vulnerability management), InsightIDR (SIEM/investigations), and Metasploit Pro (pentest telemetry) as tools for Claude, Cursor, and any MCP-compatible LLM client.
      6
      MIT