Understand how the ThreatExploit MCP Server connects your AI client to the ThreatWinds platform, and learn how to configure your environment variables for a seamless integration.
Architecture overview
The ThreatExploit MCP Server acts as the central bridge between your AI client (like Claude) and the underlying ThreatWinds infrastructure.
Instead of connecting directly to the agents, all pt-agent operations are securely proxied through the Studio API over HTTPS.
flowchart TD
Claude["AI Client (Claude)"] -- MCP --> MCPServer["MCP Server"]
MCPServer -- HTTPS --> StudioAPI["Studio API"]
StudioAPI -- HTTP --> PTAgent["pt-agent"]
MCPServer -- HTTPS --> TWAPI["ThreatWinds API (billing, compute, auth)"]How tool execution works
The MCP server is designed to be resilient and self-healing. It automatically discovers running pt-agent instances using the ThreatWinds compute API. When a tool is called, the server follows this routing process:
- 1
Query for instances
The server queries the ThreatWinds compute API to find any currently running compute instances.
- 2
Select the target
It picks the internal IP address of the first running instance it finds to use as the target.
- 3
Boot instances on demand
If no running instances are found, the server automatically starts a terminated instance and waits for it to fully boot.
- 4
Route and cache
The target IP is cached and passed to the Studio API using the
X-Target-Serverheader. If the connection ever fails, the server automatically flushes the cache and re-discovers the instances.
Configuration
To authenticate and connect your MCP server, you need to configure your environment variables. Create a .env file in the root of your project and add the following configuration:
# ThreatExploit MCP Server Configuration
# Your ThreatWinds bearer token (required)
BEARER_TOKEN=your_secure_token_here
# Studio API URL — all pt-agent operations are proxied through this
STUDIO_API_URL=https://studio.dev.threatexploit.ai
# ThreatWinds platform API (default shown — change for production)
THREATWINDS_API_URL=https://apis.dev.threatwinds.com/api
# pt-agent HTTP port (default: 9741)
PT_AGENT_PORT=9741Never commit your .env file or your BEARER_TOKEN to version control. Always use a secure secrets manager or environment variables in your deployment environment.
Environment variables reference
| Variable | Required | Default | Description |
|---|---|---|---|
BEARER_TOKEN | Yes | - | Your primary authentication token for the ThreatWinds platform. |
STUDIO_API_URL | No | https://studio.dev.threatexploit.ai | The proxy URL for all agent operations. |
THREATWINDS_API_URL | No | https://apis.dev.threatwinds.com/api | The core platform API used for billing, compute, and auth. Update this for production. |
PT_AGENT_PORT | No | 9741 | The HTTP port that the pt-agent listens on. |
Available MCP tools
Once configured, the MCP server exposes several tools to your AI client, categorized by their function. You can explore the available tools below:
Interpret & Tasks
These tools handle the core penetration testing workflows and task management.
| Tool | Description |
|---|---|
interpret | Parse natural-language input into structured pentest commands. |
list_tasks / get_task | Browse custom task sessions. |
cancel_task | Close a running task. |
download_task | Get the download URL for task evidence. |
Infrastructure
These tools allow you to manage the compute instances where your agents run.
| Tool | Description |
|---|---|
get_status | Check agent connection, version, and all instance statuses. |
get_version | Get the pt-agent version. |
tw_list_instances / tw_get_instance | List and inspect compute instances. |
tw_instance_action | Start, stop, or restart an instance. |
tw_create_instance / tw_destroy_instance | Create or destroy instances. |
tw_list_templates / tw_get_template_zones | Browse instance templates and available zones. |
Billing & Account
These tools provide visibility into your account usage, limits, and active sessions.
| Tool | Description |
|---|---|
tw_get_session / tw_list_sessions | Retrieve active session information. |
tw_get_billing_tier | Check your current plan tier. |
tw_get_limits / tw_get_usage | View plan limits and current usage. |
tw_get_quotas / tw_get_quota_usage | View specific quotas and their usage. |
tw_verify_status | Check your account verification status. |