CAPE Sandbox MCP Server

This MCP (Model Context Protocol) server allows AI agents (like Antigravity, Gemini, Claude Desktop, Cursor, etc.) to interact directly with your CAPE Sandbox instance.

Features

Exposes the following tools to AI agents:

Task Submission:

submit_file: Submit a local file for sandbox analysis.
submit_url: Submit a URL for sandbox analysis.
submit_dlnexec: Submit a URL for “Download & Execute” analysis.
submit_static: Submit a file for static extraction only.

Task Management & Search:

search_task: Find previous analyses by MD5/SHA1/SHA256 hashes.
extended_search: Advanced search by various criteria (filename, type, ssdeep, etc.).
list_tasks: List recent tasks with optional status filtering.
view_task: Get detailed information about a specific task.
get_task_status: Check if an analysis is pending, running, or completed.
reschedule_task: Reschedule a task to run again.
reprocess_task: Reprocess a task’s existing data.
delete_task: Delete a task from the database.

Reports & Intelligence:

get_task_report: Retrieve analysis reports (json, maec, etc.).
get_task_iocs: Retrieve Indicators of Compromise (IOCs).
get_task_config: Retrieve extracted malware configuration.
get_statistics: Get global task statistics.
get_latest_tasks: Get IDs of recently finished tasks.

Downloads:

download_task_screenshot: Download analysis screenshots.
download_task_pcap: Download network traffic capture (PCAP).
download_task_tlspcap: Download TLS-decrypted network traffic.
download_task_dropped: Download files dropped during analysis.
download_self_extracted_files: Download files extracted by CAPE (e.g. unpacked payloads).
download_task_payloadfiles: Download CAPE payload files.
download_task_procdumpfiles: Download process dumps.
download_task_procmemory: Download process memory dumps.
download_task_fullmemory: Download full VM memory dump.
download_task_evtx: Download Windows Event Logs (EVTX).
download_task_surifile: Download Suricata captured files.
download_task_mitmdump: Download mitmdump HAR file.

Infrastructure & Files:

list_machines: See available analysis VMs.
view_machine: Get details about a specific VM.
list_exitnodes: List available network exit nodes.
view_file: Get information about a file in the database.
download_sample: Download a malware sample from the database.
get_cuckoo_status: Get the health/status of the CAPE host.

Installation

You can install the required dependencies using the mcp extra:

poetry run pip install .[mcp]

Configuration

The MCP server integrates with CAPE’s standard configuration system and environment variables.

Environment Variables

CAPE_API_URL: (Optional) The full path to your CAPE API v2 endpoint (e.g., http://127.0.0.1:8000/apiv2). If not set, it defaults to the url in api.conf + /apiv2.
CAPE_API_TOKEN: (Optional) Your API token. Recommended to set this in the Client Configuration (e.g. claude_desktop_config.json) rather than your system’s global environment variables to ensure isolation.
CAPE_ALLOWED_SUBMISSION_DIR: (Optional) Restricts submit_file to a specific local directory for security. Defaults to the current working directory.
CAPE_MCP_TRANSPORT: (Optional) The transport protocol to use (stdio, sse, streamable-http, http). Defaults to stdio.
CAPE_MCP_HOST: (Optional) Host to bind for network transports. Defaults to 127.0.0.1.
CAPE_MCP_PORT: (Optional) Port to bind for network transports. Defaults to 8000.

Granular Tool Control (`api.conf`)

You can enable or disable specific tools for the MCP server by modifying conf/api.conf. Each API section now supports an mcp toggle:

[filecreate]
enabled = yes
mcp = yes    # Set to 'no' to hide this tool from the AI agent

[taskdelete]
enabled = no
mcp = no     # AI will not see 'delete_task'

Note: Tools disabled via mcp = no are not even registered with the MCP server; the AI agent will not see them in its available toolset.

Authentication & Security Architecture

Proper security depends on how you deploy the MCP server.

Scenario A: Local / Stdio (Recommended)

In this mode, the AI Client (Claude, Gemini, etc.) spawns a private instance of the MCP server process for your session. This is the most secure method.

Configuration: Add your CAPE_API_TOKEN to the Client’s Configuration file (e.g., claude_desktop_config.json), not your system’s global environment variables.
Isolation: Because the process is spawned by your client, the token is isolated to your session. Other users on the machine cannot see or use your token.
Usage: You do not need to provide a token in your prompts. The server automatically uses the environment variable provided by the client.

Scenario B: Remote / Shared Server (SSE)

In this mode, a single MCP server instance runs continuously and accepts connections from multiple clients over the network.

Execution: Start the server using poetry run python mcp/server.py --transport sse.
Configuration: Start the server without a CAPE_API_TOKEN environment variable.
Strict Mode: Ensure token_auth_enabled = yes is set in conf/api.conf.
Usage: Users must provide their API token in the token argument for every tool call (e.g., submit_file(..., token="MyKey")).
Risk: Do not set a global token in this mode, or all users will inherit those privileges.

Authentication Priority

The server determines which token to use in this specific order:

Per-Request Token: Argument passed to the specific tool (e.g., token="xyz").
Environment Token: CAPE_API_TOKEN variable (set in Client Config for Stdio).

If token_auth_enabled = yes and no token is found in either location, the request is rejected.

Running the Server

Standard execution (Stdio)

CAPE_API_URL=http://your-cape-ip:8000/apiv2 CAPE_API_TOKEN=your_token poetry run python mcp/server.py

Remote / SSE execution

To run the server as a persistent service accessible over the network:

poetry run python mcp/server.py --transport sse --port 9004

Deployment behind Nginx

When running behind an Nginx reverse proxy, you must expose both the /sse and /messages endpoints and disable buffering to allow the event stream to function.

location /sse {
    proxy_pass http://127.0.0.1:9004/sse;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 24h;
}

location /messages {
    proxy_pass http://127.0.0.1:9004/messages;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_buffering off;
}

Client Integrations

The CAPE MCP server can be used with any MCP-compliant client. Here are examples for popular clients.

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "cape": {
      "command": "poetry",
      "args": ["run", "python", "/opt/CAPEv2/mcp/server.py"],
      "env": {
        "CAPE_API_URL": "http://127.0.0.1:8000/apiv2",
        "CAPE_API_TOKEN": "YOUR_API_TOKEN_HERE",
        "CAPE_ALLOWED_SUBMISSION_DIR": "/home/user/samples"
      }
    }
  }
}

Gemini CLI

You can add the server using the CLI command:

gemini mcp add cape poetry run python /opt/CAPEv2/mcp/server.py \
  -e CAPE_API_URL=http://127.0.0.1:8000/apiv2 \
  -e CAPE_API_TOKEN=YOUR_API_TOKEN_HERE \
  -e CAPE_ALLOWED_SUBMISSION_DIR=/home/user/samples

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

{
  "mcpServers": {
    "cape": {
      "command": "poetry",
      "args": ["run", "python", "/opt/CAPEv2/mcp/server.py"],
      "env": {
        "CAPE_API_URL": "http://127.0.0.1:8000/apiv2",
        "CAPE_API_TOKEN": "YOUR_API_TOKEN_HERE",
        "CAPE_ALLOWED_SUBMISSION_DIR": "/home/user/samples"
      }
    }
  }
}

Antigravity

Open Agent Panel -> … -> MCP Servers -> Manage MCP Servers -> View raw config and add the following to mcp_config.json:

{
  "mcpServers": {
    "cape": {
      "command": "poetry",
      "args": ["run", "python", "/opt/CAPEv2/mcp/server.py"],
      "env": {
        "CAPE_API_URL": "http://127.0.0.1:8000/apiv2",
        "CAPE_API_TOKEN": "YOUR_API_TOKEN_HERE",
        "CAPE_ALLOWED_SUBMISSION_DIR": "/home/user/samples"
      }
    }
  }
}

Security Note

Tool Filtering: Use the mcp = no setting in api.conf to hide dangerous operations (like task_delete) from the AI.
Path Restriction: Use CAPE_ALLOWED_SUBMISSION_DIR to ensure the AI cannot submit arbitrary sensitive files from your host system.
Auth Enforcement: Enable token_auth_enabled in api.conf to ensure all interactions are authenticated.