InsightAppSec MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@InsightAppSec MCP Server list vulnerabilities for the main web app"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Node.js 18.0.0 or higher
A Rapid7 InsightAppSec account with API access
An API key from the Rapid7 Insight Platform
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 buildConfiguration
Create a .env file based on the provided template:
cp .env.example .envEdit the .env file with your credentials:
INSIGHTAPPSEC_API_KEY=your-api-key-here
INSIGHTAPPSEC_REGION=usSupported Regions:
Region | Code |
United States |
|
Europe |
|
Asia-Pacific |
|
Canada |
|
Australia |
|
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 all applications with pagination and sorting |
| Get detailed information about a specific application |
| Create a new application |
| Update application name or description |
| Delete an application and all associated data |
| Add or remove tags from an application |
Scan Operations
Tool | Description |
| List scans with pagination and filtering |
| Get detailed information about a specific scan |
| Submit a new scan based on a scan configuration |
| Delete a failed scan |
| Pause, resume, stop, or cancel a running scan |
| Get real-time execution metrics for a scan |
| Get engine event logs for a scan |
Scan Configuration
Tool | Description |
| List all scan configurations |
| Get details of a specific scan configuration |
| Create a new scan configuration |
| Update scan configuration settings |
| Delete a scan configuration |
Vulnerability Management
Tool | Description |
| List vulnerabilities with pagination and sorting |
| Get detailed information about a vulnerability |
| Update vulnerability status or severity |
| Get discovery history for a vulnerability |
| List all comments on a vulnerability |
| Add a comment to a vulnerability |
Scheduling & Automation
Tool | Description |
| List all scan schedules |
| Get details of a specific schedule |
| Create a recurring scan schedule |
| Update schedule frequency or timing |
| Delete a scan schedule |
Blackout Windows
Tool | Description |
| List all blackout windows |
| Get details of a specific blackout window |
| Create a blackout window to prevent scans |
| Update blackout window settings |
| Delete a blackout window |
Reporting
Tool | Description |
| List all generated reports |
| Generate a new vulnerability report |
| Check the status of a report generation |
Search
Tool | Description |
| Universal search across all InsightAppSec resources using DSL query syntax |
Infrastructure
Tool | Description |
| List all registered scan engines |
| Get details of a specific scan engine |
| List all engine groups |
| Get details of a specific engine group |
File Management
Tool | Description |
| List all files for an application (macros, traffic, selenium, etc.) |
| Get file metadata by ID |
| Create file metadata entry |
| Upload binary file content (base64-encoded) |
| Delete a 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 full scan config options including auth settings |
| Configure form-based authentication (username/password) |
| Configure OAuth 2.0 authentication |
| Configure global token extraction/injection rules |
| Configure session detection, cookies, relogin triggers |
| Configure automatic CSRF token detection and injection |
| Link a macro file to scan config for authentication |
| 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:
Use
list_scan_configsto find the configurationUse
submit_scanto start the scanReport 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:
Use
update_vulnerabilityto set status toFALSE_POSITIVEUse
add_vulnerability_commentto 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:
WEEKLYStart 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_CREDENTIALSToken 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: trueOptional regex patterns for token names
Upload Authentication Macro
"Upload my recorded login macro for the scan"
The assistant will:
Use
create_fileto create metadata (type: MACRO)Use
upload_file_contentwith base64-encoded macro contentUse
configure_macro_authto link it to the scan config
Search Query Syntax
The search tool supports a powerful DSL for querying resources:
Operators
Operator | Description | Example |
| Equals |
|
| Not equals |
|
| Comparison |
|
| Substring match |
|
| Value in list |
|
| Logical operators |
|
Searchable Resource Types
VULNERABILITYSCANSCAN_CONFIGAPPSCHEDULEBLACKOUTMODULEATTACK_TEMPLATEENGINEENGINE_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 authenticationAUTHORIZATION_CODE- User-delegated accessRESOURCE_OWNER_PASSWORD- Direct username/passwordIMPLICIT- 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_COOKIERESPONSE_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: trueMacro-Based Authentication
Use recorded macros for complex authentication flows:
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>"Configure the scan to use it:
configure_macro_auth:
scan_config_id: "uuid"
macro_file_id: "uuid"
replay_speed: 1.0Vulnerability Statuses
Status | Description |
| New vulnerability, not yet triaged |
| Determined to be a false positive |
| Confirmed as a real vulnerability |
| Acknowledged but accepted risk |
| Fixed in the application |
| Duplicate of another finding |
Severity Levels
Severity | Description |
| No security impact |
| Information disclosure |
| Minor security concern |
| Moderate security risk |
| 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.exampleScripts
# Build the project
npm run build
# Run in development mode
npm run dev
# Type checking
npm run typecheck
# Run tests
npm testAdding New Tools
Create or modify a tool file in
src/tools/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);
}
);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 toolsadd_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).
searchA
Universal search across InsightAppSec resources using DSL query syntax.
Examples:
Search high severity vulns: type=VULNERABILITY, query="vulnerability.severity='HIGH'"
Search running scans: type=SCAN, query="scan.status='RUNNING'"
Search apps by name: type=APP, query="app.name CONTAINS 'prod'"
Query operators: =, !=, <, >, <=, >=, CONTAINS, IN, AND, OR
Inputs: type (required), query (required), size, index.
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
Scored across 56 tools
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.
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.
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.
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
Related MCP Connectors
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Related MCP Servers
- AlicenseBqualityDmaintenanceProvides 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.1157 PyPI21MIT
- AlicenseAqualityDmaintenanceA 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.84MIT
- FlicenseNot gradedqualityDmaintenanceA remote MCP server that exposes mock application security testing data (applications, scans, issues) for LLM clients to query security posture using natural language.-
- AlicenseNot gradedqualityDmaintenanceA 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.6MIT