---
title: "MCP Server for AI-Assistant-Driven Pentesting"
description: "Learn how to use TurboPentest's MCP Server to launch and manage pentests directly from AI-powered code editors and assistants."
canonical: https://turbopentest.com/learn/integration-automation/mcp-server
source: "TurboPentest Learn"
---

# MCP Server for AI-Assistant-Driven Pentesting

## What is the Model Context Protocol?

The Model Context Protocol (MCP) is an open standard that allows AI assistants to interact with external tools and services. Instead of copying and pasting between your security dashboard and your code editor, MCP lets your AI assistant talk directly to TurboPentest - launching pentests, querying results, and even acting on findings without leaving your development environment.

TurboPentest's MCP Server exposes the pentest lifecycle as MCP tools that any compatible AI assistant can call. This includes Claude Code, VS Code with Copilot, Cursor, Windsurf, and any other editor that supports the MCP standard. The local stdio server (the npm package covered below) is also listed on Smithery.

TurboPentest offers two flavors of MCP server: the local stdio server (`@turbopentest/mcp-server`, the focus of this lesson) and a remote HTTP MCP server (which additionally exposes MCP Resources). Both flavors register the **same** `turbopentest_`-prefixed tool names - for example `turbopentest_start_pentest` and `turbopentest_get_findings` - so the tool set is identical between them. Only the transport differs: the local server speaks stdio, the remote server speaks HTTP.

## Installing the MCP Server

The TurboPentest MCP Server is distributed as the npm package `@turbopentest/mcp-server`. For Claude Code, add it to a `.mcp.json` file in your project root:

```json
{
  "mcpServers": {
    "turbopentest": {
      "command": "npx",
      "args": ["@turbopentest/mcp-server"],
      "env": {
        "TURBOPENTEST_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

Claude Desktop uses the same shape in `claude_desktop_config.json`, and Cursor accepts it under Settings > MCP Servers. The server authenticates using your TurboPentest API key passed as the `TURBOPENTEST_API_KEY` environment variable. Create the key at Settings > API Keys in the dashboard.

## Available MCP Tools

The MCP Server exposes the following tools to your AI assistant:

### Pentest Lifecycle

- **turbopentest_start_pentest** - Start a new pentest with a `target_url` (must be a verified domain), an optional `repo_url` for white-box analysis, and a `tier` (`recon`, `standard`, `deep`, or `blitz`; default `standard`). Returns a pentest ID for tracking.
- **turbopentest_get_pentest** - Get full details for a pentest: status, progress, findings summary, executive summary, attack surface map, and STRIDE threat model.
- **turbopentest_list_pentests** - List your pentests with status and finding counts.
- **turbopentest_list_domains** - List your verified domains, so the assistant can check verification before launching.
- **turbopentest_get_credits** - Check your credit balance and available tiers with pricing.

### Results and Findings

- **turbopentest_get_findings** - Retrieve structured findings for a pentest, with severity, CVSS, CWE, description, proof-of-concept, and remediation steps. Returns up to 20 findings at a time; use the `severity` filter (`critical`, `high`, `medium`, `low`, `info`) to narrow results.
- **turbopentest_download_report** - Download the full report as markdown (best for AI consumption), JSON, or PDF.
- **turbopentest_verify_attestation** - Verify a pentest's cryptographic attestation by hash (public, no API key required; on-chain Base anchoring is the designed roadmap).

### Built-In Prompts

The server also ships guided prompts for multi-step workflows:

- **run_pentest** - Full lifecycle: domain check, credit verification, launch, monitoring, and summary
- **analyze_findings** - Deep-dive analysis of a pentest's findings with a prioritized remediation plan
- **compare_pentests** - Diff two pentests by fetching both with `turbopentest_get_pentest` and `turbopentest_get_findings`, then matching findings by fingerprint (falling back to title) to categorize them as new, fixed (resolved), or still-present (recurring)
- **security_posture** - Executive summary of overall security posture across recent pentests

## Workflow: Pentest from Your Editor

Here is a typical interaction with an MCP-aware AI assistant:

**You:** "Run a standard pentest against our staging environment at staging.example.com"

**Assistant:** Calls `turbopentest_start_pentest` with target `https://staging.example.com` and tier `standard`. Returns the pentest ID.

**You:** "What is the status?"

**Assistant:** Calls `turbopentest_get_pentest` with the ID. Reports: "Still scanning. 4 findings so far (1 high, 2 medium, 1 low)."

**You:** "Show me the high severity finding."

**Assistant:** Calls `turbopentest_get_findings` filtered to high severity. Returns: "SQL Injection in /api/users endpoint via the 'sort' parameter. The agent demonstrated data extraction using a UNION-based payload."

**You:** "Fix this vulnerability in our codebase."

**Assistant:** Reads the finding's remediation guidance and the relevant source file, then applies a parameterized query fix - all without leaving the editor.

This workflow compresses what would normally be a multi-day cycle (run pentest, read report, switch to IDE, find code, apply fix) into a single conversation.

## Tool Reference Details

### turbopentest_start_pentest

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| target_url | string | yes | The URL to pentest (the domain must be verified in your account) |
| repo_url | string | no | GitHub repository URL for white-box analysis (SAST, secret detection, dependency audit) |
| tier | string | no | recon, standard, deep, or blitz (default: standard) |

### turbopentest_get_findings

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| pentest_id | string | yes | The pentest to query (UUID) |
| severity | string | no | Filter by severity (critical, high, medium, low, info) |

## Security Considerations

The MCP Server runs locally on your machine and communicates with TurboPentest's API over HTTPS. Your API key never leaves your local environment. The server does not store any pentest data locally - all data remains in TurboPentest's infrastructure.

For team environments, each developer should use their own named API key rather than sharing one. Keys have full account access, so treat them like passwords and revoke any key that may have been exposed.

## Advantages Over the Web Dashboard

While the TurboPentest web dashboard provides a full-featured interface for managing pentests, the MCP Server offers unique advantages for developers:

- **No context switching** - Stay in your editor throughout the entire pentest-review-fix cycle
- **AI-assisted remediation** - Your AI assistant can read findings and apply fixes in the same conversation
- **Programmatic filtering** - Query findings by severity without navigating a UI
- **Natural language interaction** - Ask questions about findings in plain English rather than navigating menus
- **Guided workflows** - Built-in prompts walk the assistant through launches, analysis, and run-to-run comparisons using conversational commands