MCP overview

The Model Context Protocol (MCP) server provides a standardized interface that lets any compatible AI model or agent access your Pentest-Tools.com account, running scans, managing targets, retrieving findings, and generating reports. Connect to our MCP server in Claude, Cursor, VS Code, and other clients using either the local server or our hosted remote server.

Setup instructions

General

Our MCP server supports both local (stdio) and remote (HTTP) transports:

Transport	Address
Local	`ptt mcp` (requires `pip install pentesttools[mcp]`)
Remote	`https://mcp.pentest-tools.com/mcp`

Authentication requires your Pentest-Tools.com API key. Get it from My Account > API in the web application.

API access requires a paid plan that includes it. See Authentication for details.

Claude Code

claude mcp add --transport http ptt-mcp https://mcp.pentest-tools.com/mcp --header "Authorization: Bearer your_api_key_here"

Claude Desktop

Edit your Claude Desktop configuration file:

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

Local server

{
  "mcpServers": {
    "ptt-mcp": {
      "command": "ptt",
      "args": ["mcp"],
      "env": {
        "PTT_API_KEY": "your_api_key_here"
      }
    }
  }
}

Remote server Claude Desktop only supports local, stdio-based communication. Its paid plan Connectors don’t support custom headers, so you need npx mcp-remote as a local bridge to the remote server. Make sure npm is installed before you start.

{
  "mcpServers": {
    "ptt-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.pentest-tools.com/mcp", "--header", "Authorization: Bearer your_api_key_here"]
    }
  }
}

Restart Claude Desktop after saving.

Claude Desktop now supports local MCP servers across both their Free and Paid plans and requires updating claude_desktop_config.json. Even though paid plans usually allow connection with a Remote MCP server through “Connectors”, the feature does not support Custom Headers, which our server requires for authentication.

Cursor

Paste this URL into your browser. Add your API key after installation.

cursor://anysphere.cursor-deeplink/mcp/install?name=ptt-mcp&config=eyJ1cmwiOiJodHRwczovL21jcC5wZW50ZXN0LXRvb2xzLmNvbS9tY3AiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIgeW91cl9hcGlfa2V5X2hlcmUifX0=

Or configure manually: Local server

{
  "servers": {
    "ptt-mcp": {
      "type": "stdio",
      "command": "ptt",
      "args": ["mcp"],
      "env": {
        "PTT_API_KEY": "your_api_key_here"
      }
    }
  }
}

Remote server

{
  "servers": {
    "ptt-mcp": {
      "type": "http",
      "url": "https://mcp.pentest-tools.com/mcp",
      "headers": {
        "Authorization": "Bearer your_api_key_here"
      }
    }
  }
}

Visual Studio Code

Press Ctrl/Cmd + P and search for MCP: Add Server
Select Command (stdio)
Enter: ptt mcp
Set environment variable PTT_API_KEY to your API key

Or add manually to your settings:

{
  "servers": {
    "ptt-mcp": {
      "type": "stdio",
      "command": "ptt",
      "args": ["mcp"],
      "env": {
        "PTT_API_KEY": "your_api_key_here"
      }
    }
  }
}

Gemini CLI

gemini mcp add ptt-mcp --transport http https://mcp.pentest-tools.com/mcp --header "Authorization: Bearer your_api_key_here"

Or add manually to ~/.gemini/settings.json:

{
  "mcpServers": {
    "ptt-mcp": {
      "httpUrl": "https://mcp.pentest-tools.com/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer your_api_key_here"
      }
    }
  }
}

Others

Configure other MCP-compatible tools with:

Setting	Local	Remote
Command	`ptt`	-
Arguments	`mcp`	-
URL	-	`https://mcp.pentest-tools.com/mcp`
Environment	`PTT_API_KEY=your_api_key`	-
Headers	-	`Authorization: Bearer your_api_key`

Installation

For local server usage, install the Python package:

pip install pentesttools[mcp]

Python 3.10 or higher is required.

Available tools

The MCP server provides tools for:

Category	Tools
Scanning	Perform a Website Scanner, Subdomain Finder or Network Scanner
Resource Management	Everything you need to manage your scans, targets, workspaces, and findings: list, filter, create, or delete.
Reports	Create, download, delete reports
Utilities	HTTP loggers, VPN profiles, report translation

Read-only resources

The MCP server also exposes read-only resources (scans, targets, workspaces, findings, reports, HTTP loggers, and wordlists) so the LLM has context before you even ask anything. Resources and tools do different things: resources answer questions (“What are my findings?”), tools take action (“Start a new scan”).

Built-in prompts

Pre-built prompts for common workflows:

Name	Prompt
`pentest`	“Please provide a comprehensive pentesting report for this target: target, using the tools at your disposal.”
`subdomains`	“Please find all the subdomains that you can for this domain: target, using the tools at your disposal.”
`summary`	“Please create an executive summary for the latest scans in the workspace workspace_id, using the tools at your disposal.”
`vibeseccoding`	Summarised: Scan a local Dockerized application and attempt to remediate findings

Use cases

Use the MCP server to chain tools together and run multi-step security workflows through natural language.

Rapid reconnaissance

Map a target’s attack surface without running each scanner manually. Ask the AI to perform a recon scan, and it will call the subdomain finder, review the results, and run the network scanner on live assets to find open ports.

Smart vulnerability triage

Ask the AI to pull findings from a workspace and summarize only the critical SQL injection vulnerabilities from that week. It filters by your criteria and explains the results, which is faster than scrolling through the dashboard.

Report translation

The translate_report tool fetches the report, translates each finding, imports the translated versions, and generates a new report for your regional teams. The limit is 50 findings per hour, so start with smaller reports or allow extra time for large ones.

When downloading a PDF report via MCP, tell the AI to save it to a local file rather than display it. The API returns raw binary data, which can flood your context window with unreadable text.

Executive reporting

Use the summary prompt to get a risk overview with remediation priorities, written for people who don’t need to know what a CVE is.

Secure coding

For developers using agentic IDEs like Cursor or Copilot. Run a scan on your local Docker app, and the AI reads the relevant source files, proposes patches, and confirms the fix with a follow-up scan.

Limitations

Tool count: The server exposes a small number of tools on purpose (Website Scanner, Network Scanner and Subdomain Finder). Most LLM clients perform worse as the tool count grows. Progress reporting: Scans report progress via scan ID and status updates. Some clients, including VS Code, can’t display progress bars for long-running operations. Authenticated scanning: The Website Scanner supports login form, cookie, and header authentication, but not recorded authentication, as our API does not support the recorded method either. Plan limits: Your scan capacity (parallel scans, assets per cycle, and queued scans) depends on Pentest-tools.com subscription plan. Hitting these limits will cause queueing, delays, or errors. The LLM can only work with assets within your plan’s scope. Parallel scanning: Most MCP tools provided are not truly asynchronous at the moment. Deep and Custom scans are configured to return control and do not wait for the response. For Light, the MCP client will ask whether you want to wait for scans to complete. Report translation quota: translate_report is limited to roughly 50 findings per hour.

FAQ

What plans support API/MCP access?

MCP Server features require a Pentest-Tools.com API key. All paid plans include API access, so that MCP tools will work out of the box.

Local vs remote server, which should I use?

Use the remote server for simpler setup without local dependencies. Use the local server if you have Python installed and want faster response times.

How do I scan internal or private targets?

Use get_vpn_profiles to retrieve your VPN profile UUIDs, then pass vpn_profile_uuid to your scan tool. If a target IP is private (RFC 1918), always include a VPN profile. Don’t wait for the scan to fail before checking.

How do I know what tools the AI is calling?

Most MCP clients ask for permission before calling tools. This is helpful for understanding what actions the AI takes. You can disable this once you’re confident in the workflow.

API examples: Python examples for direct API usage
Authentication: API authentication details

Intro

Core

Tools reference

Capabilities

AI

Account & billing

Setup instructions

General

Claude Code

Claude Desktop

Cursor

Visual Studio Code

Gemini CLI

Others

Installation

Available tools

Read-only resources

Built-in prompts

Use cases

Rapid reconnaissance

Smart vulnerability triage

Report translation

Executive reporting

Secure coding

Limitations

FAQ

Intro

Core

Tools reference

Capabilities

AI

Account & billing

​Setup instructions

​General

​Claude Code

​Claude Desktop

​Cursor

​Visual Studio Code

​Gemini CLI

​Others

​Installation

​Available tools

​Read-only resources

​Built-in prompts

​Use cases

​Rapid reconnaissance

​Smart vulnerability triage

​Report translation

​Executive reporting

​Secure coding

​Limitations

​FAQ

​Related topics

Setup instructions

General

Claude Code

Claude Desktop

Cursor

Visual Studio Code

Gemini CLI

Others

Installation

Available tools

Read-only resources

Built-in prompts

Use cases

Rapid reconnaissance

Smart vulnerability triage

Report translation

Executive reporting

Secure coding

Limitations

FAQ

Related topics