> ## Documentation Index
> Fetch the complete documentation index at: https://pentest-tools.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP overview

> Connect AI assistants to Pentest-Tools.com using the Model Context Protocol

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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.

<Info>
  API access requires a paid plan that includes it. See [Authentication](/api-reference/authentication) for details.
</Info>

### Claude Code

```shell theme={null}
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**

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

<Info>
  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.
</Info>

### Cursor

Paste this URL into your browser. Add your [API key](/api-reference/authentication) after installation.

```text theme={null}
cursor://anysphere.cursor-deeplink/mcp/install?name=ptt-mcp&config=eyJ1cmwiOiJodHRwczovL21jcC5wZW50ZXN0LXRvb2xzLmNvbS9tY3AiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIgeW91cl9hcGlfa2V5X2hlcmUifX0=
```

Or configure manually:

**Local server**

```json theme={null}
{
  "servers": {
    "ptt-mcp": {
      "type": "stdio",
      "command": "ptt",
      "args": ["mcp"],
      "env": {
        "PTT_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

**Remote server**

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

### Visual Studio Code

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

Or add manually to your settings:

```json theme={null}
{
  "servers": {
    "ptt-mcp": {
      "type": "stdio",
      "command": "ptt",
      "args": ["mcp"],
      "env": {
        "PTT_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### Gemini CLI

```shell theme={null}
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`:

```json theme={null}
{
  "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:

```bash theme={null}
pip install pentesttools[mcp]
```

<Note>
  Python 3.10 or higher is required.
</Note>

## Available tools

The MCP server provides [tools](/ai/mcp/mcp-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.

<Tip>
  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.
</Tip>

### 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 [<u>Pentest-tools.com</u>](http://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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Related topics

* [API examples](/api-reference/examples): Python examples for direct API usage
* [Authentication](/api-reference/authentication): API authentication details