MCP Snapshots & Raw Capture Tools

Kubeshark’s MCP server exposes snapshot and raw capture tools that enable AI assistants to create point-in-time traffic snapshots, query data boundaries, and export PCAP files for external analysis.

MCP Endpoints Overview

Endpoint: /mcp/raw-capture

Check if raw packet capture is enabled.

Response

{
  "enabled": true,
  "session_id": "abc123"
}

Raw capture must be enabled to create snapshots and export PCAP files.

Endpoint: /mcp/data-boundaries

Get the available time range for snapshots and queries.

Response

{
  "cluster": {
    "oldest_ts": 1706745000000,
    "newest_ts": 1706748600000
  },
  "nodes": [
    {
      "name": "worker-1",
      "oldest_ts": 1706745000000,
      "newest_ts": 1706748600000
    },
    {
      "name": "worker-2",
      "oldest_ts": 1706745100000,
      "newest_ts": 1706748600000
    }
  ]
}

Use this to understand what time range of data is available before creating snapshots.

Example Request

GET /mcp/data-boundaries
→ "What time range of traffic data is available?"
→ "How far back can I create a snapshot?"

Snapshot Endpoints

Snapshots capture a point-in-time view of traffic for later analysis or export.

POST /mcp/snapshots

Create a new snapshot.

Request:

{
  "name": "incident-001",
  "duration": "1h"
}

Response:

{
  "success": true,
  "name": "incident-001",
  "status": "in_progress"
}

GET /mcp/snapshots

List all snapshots.

{
  "snapshots": [
    {
      "name": "incident-001",
      "status": "completed",
      "size_bytes": 52428800,
      "created_at": "2025-01-15T10:30:00Z",
      "duration": "1h"
    },
    {
      "name": "debug-session",
      "status": "in_progress",
      "size_bytes": 10485760,
      "created_at": "2025-01-15T11:00:00Z",
      "duration": "30m"
    }
  ]
}

GET /mcp/snapshots/:name

Get details for a specific snapshot.

{
  "name": "incident-001",
  "status": "completed",
  "size_bytes": 52428800,
  "created_at": "2025-01-15T10:30:00Z",
  "duration": "1h",
  "start_ts": 1706745000000,
  "end_ts": 1706748600000,
  "node_count": 3,
  "packet_count": 1500000
}

DELETE /mcp/snapshots/:name

Delete a snapshot.

{
  "success": true,
  "name": "incident-001"
}

GET /mcp/snapshots/:name/pcap

Export snapshot as a merged PCAP file for Wireshark analysis. Supports optional filtering by nodes, time range, and BPF expression to extract only the packets you need.

Returns binary PCAP data with Content-Type: application/vnd.tcpdump.pcap.

Query Parameters

All parameters are optional. When omitted, the full unfiltered snapshot is exported.

Examples

Export the full snapshot:

curl http://localhost:8898/mcp/snapshots/incident-001/pcap -o snapshot.pcap

Export only HTTP traffic:

curl "http://localhost:8898/mcp/snapshots/incident-001/pcap?bpf_filter=tcp%20port%2080" -o http-only.pcap

Export from a specific node within a time window:

curl "http://localhost:8898/mcp/snapshots/incident-001/pcap?nodes=worker-1&start_time=1706745000000&end_time=1706746000000" -o filtered.pcap

Export only DNS traffic:

curl "http://localhost:8898/mcp/snapshots/incident-001/pcap?bpf_filter=udp%20port%2053" -o dns.pcap

MCP Tool Usage

The export_snapshot_pcap MCP tool exposes the same filtering capabilities:

{
  "tool": "export_snapshot_pcap",
  "arguments": {
    "id": "f4c41e9c-28b9-4c9d-8ddb-128cd7e09ff3",
    "nodes": ["worker-1", "worker-2"],
    "bpf_filter": "tcp port 443",
    "start_time": 1706745000000,
    "end_time": 1706746000000
  }
}

File Download Tools

When export_snapshot_pcap (or other tools) return a relative file path, use these tools to retrieve the file. They are available in all MCP server modes (proxy, URL, destructive).

get_file_url

Resolves a relative file path into a fully-qualified download URL that can be shared with the user for manual download.

Example:

{
  "tool": "get_file_url",
  "arguments": {
    "path": "/mcp/snapshots/f4c41e9c/pcap"
  }
}

Response: A full URL like http://localhost:8898/api/mcp/snapshots/f4c41e9c/pcap

download_file

Downloads a file from Kubeshark to the local filesystem. This is the preferred way to retrieve PCAP exports. Uses a dedicated HTTP client with streaming support for large files (up to 10 GB).

Example:

{
  "tool": "download_file",
  "arguments": {
    "path": "/mcp/snapshots/f4c41e9c/pcap",
    "dest": "/tmp/incident.pcap"
  }
}

Response:

{
  "url": "http://localhost:8898/api/mcp/snapshots/f4c41e9c/pcap",
  "path": "/tmp/incident.pcap",
  "size": 52428800
}

Typical PCAP Export Workflow

1. Export — Call export_snapshot_pcap with optional filters. It returns a relative file path.
2. Download — Call download_file with that path to save the PCAP locally.
3. Share — Alternatively, call get_file_url to get a download URL to share with others.

export_snapshot_pcap → relative path → download_file → local .pcap file
                                     → get_file_url  → shareable URL

Cloud Storage Tools

These tools manage snapshot upload/download to cloud object storage (Amazon S3 or Azure Blob Storage). Cloud storage must be configured via Helm values before these tools can be used.

get_cloud_storage_status

Check whether cloud storage is configured and connected.

Parameters: None

Response:

{
  "enabled": true,
  "provider": "s3",
  "connected": true
}

upload_snapshot_to_cloud

Upload a completed snapshot to cloud storage. The operation runs asynchronously — use get_cloud_job_status to poll progress.

Example:

{
  "tool": "upload_snapshot_to_cloud",
  "arguments": {
    "id": "incident-001"
  }
}

Response:

{
  "success": true,
  "job_id": "job-abc123"
}

The snapshot must be in completed status before uploading.

download_snapshot_from_cloud

Download a snapshot from cloud storage to the local hub. The operation runs asynchronously — use get_cloud_job_status to poll progress.

Example:

{
  "tool": "download_snapshot_from_cloud",
  "arguments": {
    "id": "incident-001"
  }
}

Response:

{
  "success": true,
  "job_id": "job-xyz789"
}

Fails if the snapshot already exists locally.

get_cloud_job_status

Poll the status of an async cloud upload or download job.

Response:

{
  "job_id": "job-abc123",
  "snapshot_id": "incident-001",
  "operation": "upload",
  "status": "completed",
  "started_at": 1706745000000,
  "completed_at": 1706745060000
}

Typical Cloud Storage Workflow

1. Check — get_cloud_storage_status to verify cloud storage is configured
2. Upload — upload_snapshot_to_cloud to start the upload (returns job_id)
3. Poll — get_cloud_job_status with the job_id until status is completed or failed

get_cloud_storage_status → upload_snapshot_to_cloud → get_cloud_job_status (poll)
                         → download_snapshot_from_cloud → get_cloud_job_status (poll)

Use Cases

Incident Evidence Collection

“Create a snapshot of the last 30 minutes for the incident”

“What time range of data do we have available?”

“Export the snapshot as PCAP for the security team”

“Export only HTTPS traffic from worker-1 during the breach window”

Snapshots preserve traffic evidence for later forensic analysis. PCAP filters let you extract exactly the traffic relevant to an incident.

Compliance & Auditing

“Create a snapshot of all traffic to the payment service”

“Export traffic from the breach window as PCAP”

“List all snapshots we’ve created this week”

PCAP exports provide immutable evidence for compliance requirements.

Offline Analysis

“Export this traffic so I can analyze it in Wireshark”

“Export only DNS traffic for the network team”

“Create a snapshot I can share with the network team”

PCAP files can be analyzed with standard network tools outside of Kubeshark. Use BPF filters to reduce file size and focus on relevant protocols.

Debugging Sessions

“Capture the next hour of traffic while I reproduce the bug”

“Save this traffic so we can review it later”

“Export just the last 5 minutes of traffic from the affected node”

Snapshots allow teams to capture traffic during debugging sessions for later review. Time range and node filters help narrow down to the relevant window.

Snapshot Lifecycle

+--------------+     +--------------+     +--------------+
|    Create    |---->| In Progress  |---->|  Completed   |
|    (POST)    |     |  (capturing) |     |   (ready)    |
+--------------+     +--------------+     +------+-------+
                                                 |
                     +--------------+            |
                     |    Export    |<-----------+
                     |    (PCAP)    |            |
                     +--------------+            |
                                                 |
                     +--------------+            |
                     | Cloud Upload |<-----------+
                     |   (async)    |            |
                     +--------------+            |
                                                 |
                     +----------------+          |
                     | Cloud Download |--------->+
                     |    (async)     |
                     +----------------+
                                                 |
                     +--------------+            |
                     |    Delete    |<-----------+
                     |              |
                     +--------------+

What’s Next

• L7 Tools Reference — Query API transactions
• L4 Tools Reference — Lightweight connectivity visibility
• Traffic Snapshots — More about snapshots
• Snapshots — Create snapshots and export PCAP