API reference

base url

https://malwagon.com

authentication

Bearer token in the Authorization header. Nothing else is accepted.

rest

Five routes under /api/v1. JSON in, JSON out, no trailing slashes.

mcp

POST /mcp, JSON-RPC 2.0, revision 2026-07-28. Enterprise plans only.

media type

application/json on every request body and every response body.

caching

Every response carries Cache-Control: no-store. No session is read or created.

Command line

The quickest path from a file on your disk to a verdict, and the one that needs no code. The client is Python, has no dependencies, and runs on Linux, macOS and Windows.

pip install malwagon
export MALWAGON_API_KEY="mwg_a1b2c3d4_kZq7Xn2R9tLpWv0sYcB4hJdF6gMaE3uNbT1xQfV5rDo"

malwagon suspicious.exe

uploading suspicious.exe (412.0 KB) to malwagon.com
scan 48213 queued
waiting for the sandbox, usually 90 to 300 seconds
  queued       0s elapsed
  running      12s elapsed
  analyzing    2m 18s elapsed

  MALICIOUS  score 88/100
  sha256 354fd5f5e4afc2280a19c8541fd4abe38bf8fb73efbeb3c2b0a4f2b1d9e0c7a1
  report https://malwagon.com/s/48213

The sandbox is chosen from the file

A Windows binary detonates on Windows, an ELF or a pip package on the Linux sandbox, a driver reaches the kernel analyzer. --os overrides it where a plan allows more than one image, but there is nothing to set for the ordinary case.

It exits with the verdict

0 clean, 1 malicious, 3 suspicious, 2 for an error, so a build step can gate on it. --json prints one object on stdout while the progress stays on stderr, which is what makes malwagon sample.bin --json | jq work while you still see the wait.

Your key is never an argument

It is read from MALWAGON_API_KEY, from a file with --api-key-file, from stdin with --api-key-stdin, or from one malwagon login. There is deliberately no --api-key flag: a credential on the command line is visible in the process list and is written verbatim into shell history.

It does not trust this server

TLS is verified and there is no flag to turn that off, redirects are reported rather than followed, and a stored key is bound to the host it was stored for. Everything the server sends is stripped of terminal control sequences before it is printed, and the verdict is read from a fixed vocabulary rather than echoed.

Free and paid

A Community key works and runs a network isolated scan, so no egress, no reputation lookups and no AI narrative. The client says which layers did not run rather than leaving an empty section to be read as "the sample did nothing".

malwagon on PyPI, and malwagon --help lists every option.

Quickstart

Mint a token in the console, POST a target, then poll the returned scan id until it reports itself terminal. Every sample on this page assumes the two environment variables below, and switches with the language control in the left rail.

export MWG_BASE="https://malwagon.com"
export MWG_TOKEN="mwg_a1b2c3d4_kZq7Xn2R9tLpWv0sYcB4hJdF6gMaE3uNbT1xQfV5rDo"

import os
import requests

BASE = os.environ.get("MWG_BASE", "https://malwagon.com")
HEADERS = {"Authorization": "Bearer " + os.environ["MWG_TOKEN"]}

$Base    = $env:MWG_BASE
if (-not $Base) { $Base = "https://malwagon.com" }
$Headers = @{ Authorization = "Bearer $env:MWG_TOKEN" }

1. Mint a token

Tokens are created at Settings, API and MCP tokens in the console. You give the token a name, decide whether it may submit, and optionally set an expiry between 1 and 365 days. The raw value is displayed once at creation and stored only as a keyed hash, so it cannot be recovered afterwards, only revoked and replaced.

mwg_a1b2c3d4_kZq7Xn2R9tLpWv0sYcB4hJdF6gMaE3uNbT1xQfV5rDo
---  --------  -------------------------------------------
 |       |                        |
 |       |                        +-- secret, 43 characters, 256 bits from a CSPRNG
 |       +--------------------------- token id, 8 hex characters, what audit logs name
 +----------------------------------- fixed prefix

2. Submit a target

Submitting queues one scan and answers 202 Accepted with the scan's identity. It spends your account's own credits and is subject to your plan's concurrency limit.

curl -sS -X POST "$MWG_BASE/api/v1/scans" \
  -H "Authorization: Bearer $MWG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"module": "url", "target": "https://invoice-portal.example/pay", "private": true}'

reply = requests.post(
    BASE + "/api/v1/scans",
    headers=HEADERS,
    json={
        "module": "url",
        "target": "https://invoice-portal.example/pay",
        "private": True,
    },
    timeout=30,
)
reply.raise_for_status()
scan_id = reply.json()["scan"]["scan_id"]

$Body = @{
    module  = "url"
    target  = "https://invoice-portal.example/pay"
    private = $true
} | ConvertTo-Json

$Reply = Invoke-RestMethod -Method Post -Uri "$Base/api/v1/scans" `
    -Headers $Headers -ContentType "application/json" -Body $Body
$ScanId = $Reply.scan.scan_id

3. Poll, then read

Poll the scan id until terminal is true. When report_available turns true, the report endpoint has a full result for you. Polling is a read, and reads have a far larger budget than submissions.

while :; do
  scan=$(curl -sS "$MWG_BASE/api/v1/scans/48213" -H "Authorization: Bearer $MWG_TOKEN")
  echo "$scan" | grep -q '"terminal": true' && break
  sleep 10
done

curl -sS "$MWG_BASE/api/v1/scans/48213/report" -H "Authorization: Bearer $MWG_TOKEN"

import time

while True:
    scan = requests.get(
        BASE + "/api/v1/scans/%d" % scan_id, headers=HEADERS, timeout=30
    ).json()["scan"]
    if scan["terminal"]:
        break
    time.sleep(10)

if scan["report_available"]:
    report = requests.get(
        BASE + "/api/v1/scans/%d/report" % scan_id, headers=HEADERS, timeout=60
    ).json()["report"]
    print(report["verdict"]["label"], report["verdict"]["score"])

do {
    Start-Sleep -Seconds 10
    $Scan = (Invoke-RestMethod -Method Get -Headers $Headers `
        -Uri "$Base/api/v1/scans/$ScanId").scan
} until ($Scan.terminal)

if ($Scan.report_available) {
    $Report = (Invoke-RestMethod -Method Get -Headers $Headers `
        -Uri "$Base/api/v1/scans/$ScanId/report").report
    "{0} {1}" -f $Report.verdict.label, $Report.verdict.score
}

Authentication

Every call authenticates with a single bearer token in the Authorization header, and with nothing else: there is no cookie fallback, no query parameter and no form field.

Authorization: Bearer mwg_a1b2c3d4_kZq7Xn2R9tLpWv0sYcB4hJdF6gMaE3uNbT1xQfV5rDo

Scopes

There are exactly two scopes, and a token's grants are fixed at creation.

What a plan has to include

The two surfaces are gated on two separate entitlements, so the same token can be accepted by one and refused by the other. The plan is read live on every call rather than stamped onto the token, so a plan change takes effect on the next request with no propagation delay.

The MCP server is included on every paid plan. Pro, Business and Team include both the REST API and not include MCP. A token minted on either of them is a perfectly valid token that authenticates on /api/ and is refused on /mcp, with the plan's own wording, before any tool runs. See Pricing.

{
  "jsonrpc": "2.0",
  "error": {
    "code": -31001,
    "message": "Unauthorized: MCP access for AI clients is not included in your plan. Upgrade to use it."
  },
  "id": 1
}

Revocation and expiry

Revocation

Immediate, from the tokens page. Revoking never cancels a scan that has already started.

Expiry

Optional, from 1 to 365 days. Leaving it empty mints a token with no expiry date.

Rotation

Mint the replacement, move your clients onto it, then revoke the old one. A token is shown once and cannot be recovered, so there is no way to re-read one you have lost.

Errors

Every JSON refusal on the REST API uses one envelope: an error object with a machine-readable code and a human-readable message. Branch on code, never on the message text.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Cache-Control: no-store
Retry-After: 2841

{
  "error": {
    "code": "rate_limited",
    "message": "api_submit is limited to 10 per 3600 seconds; try again in 2841 seconds"
  }
}

Two exits that are not JSON

Two failure modes leave the JSON contract entirely, so a client that assumes a parseable body on every response will break on them.

Wrong method

A GET to a POST-only route, or the reverse, answers 405 with an Allow header and a zero-length body. There is no error envelope to parse.

Unrouted path

A path that matches no route, such as a misspelled endpoint or a trailing slash, falls through to the site's own 404 page and returns HTML rather than JSON. Check the status code and the content type before parsing.

Rate limits and caps

Rate limits are fixed windows counted per user rather than per token, so minting a second token does not buy a second budget.

Reads have the larger budget because polling a running scan is the normal shape of an integration. Submits are hourly because each one spends credits and occupies a detonation lane, and the submit budget fails closed: if the counter itself cannot be reached the submit is refused rather than waved through. On the MCP surface the budget is charged on tools/call only, and a spent budget comes back as a tool error inside a 200 rather than as a 429.

These figures are the ones configured today and an operator can retune them, so read them from a response rather than pinning them in a client: on a 429, back off for the number of seconds the Retry-After header names.

A submission refused for credits or concurrency comes back as 400 bad_request carrying the plan's own wording, because that is a refusal you can act on. Plan figures are on the pricing page.

REST API v1

Seven routes, mounted under /api/, with no trailing slashes and no version other than v1. Each one is listed below with its signature, its parameters and a worked request.

curl -sS -X POST "$MWG_BASE/api/v1/scans" \
  -H "Authorization: Bearer $MWG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "module": "command",
        "target": "powershell -nop -w hidden -enc SQBFAFgAIAAoAE4AZQB3AC0A",
        "private": true
      }'

reply = requests.post(
    BASE + "/api/v1/scans",
    headers=HEADERS,
    json={
        "module": "command",
        "target": "powershell -nop -w hidden -enc SQBFAFgAIAAoAE4AZQB3AC0A",
        "private": True,
    },
    timeout=30,
)
if reply.status_code != 202:
    raise SystemExit(reply.json()["error"]["message"])
scan = reply.json()["scan"]

$Body = @{
    module  = "command"
    target  = "powershell -nop -w hidden -enc SQBFAFgAIAAoAE4AZQB3AC0A"
    private = $true
} | ConvertTo-Json

try {
    $Scan = (Invoke-RestMethod -Method Post -Uri "$Base/api/v1/scans" `
        -Headers $Headers -ContentType "application/json" -Body $Body).scan
} catch {
    ($_.ErrorDetails.Message | ConvertFrom-Json).error.message
}

{
  "scan": {
    "scan_id": 48213,
    "module": "command",
    "status": "queued",
    "verdict": null,
    "score": null,
    "tags": {"items": [], "returned": 0, "total": 0, "truncated": false},
    "submitted_at": "2026-08-30T09:14:02.118433+00:00",
    "finished_at": null,
    "sha256": "0d4a9f6be3c25f18a7c0e9b41d2f8a6c53e7b0149ad6c8f2317be0d54c9a1f7e",
    "size": 58,
    "mime": "text/plain",
    "terminal": false,
    "report_available": false
  }
}

curl -sS -X POST "$MWG_BASE/api/v1/scans/file" \
  -H "Authorization: Bearer $MWG_TOKEN" \
  -F "[email protected]" \
  -F "private=true"

with open("suspicious.exe", "rb") as handle:
    scan = requests.post(
        BASE + "/api/v1/scans/file",
        headers=HEADERS,
        files={"file": ("suspicious.exe", handle)},
        data={"private": "true"},
        timeout=300,
    ).json()["scan"]

print(scan["scan_id"])

$Form = @{ file = Get-Item "suspicious.exe"; private = "true" }
$Scan = (Invoke-RestMethod -Method Post -Uri "$Base/api/v1/scans/file" `
  -Headers $Headers -Form $Form).scan
$Scan.scan_id

{
  "scan": {
    "scan_id": 48219,
    "module": "file",
    "status": "queued",
    "verdict": null,
    "score": null,
    "tags": {"items": [], "returned": 0, "total": 0, "truncated": false},
    "submitted_at": "2026-09-05T21:18:07.482119+00:00",
    "finished_at": null,
    "sha256": "354fd5f5e4afc2280a19c8541fd4abe38bf8fb73efbeb3c2b0a4f2b1d9e0c7a1",
    "size": 421888,
    "mime": "application/x-dosexec",
    "terminal": false,
    "report_available": false
  }
}

curl -sS -X POST "$MWG_BASE/api/v1/scans/bulk" \
  -H "Authorization: Bearer $MWG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "submissions": [
          {"module": "hash",    "target": "9c1f0b6d2ae74318bd50c7a9e6f34182bb0d5e7c94a2f61038de7b5c0a91f2d4"},
          {"module": "package", "target": "requests==2.31.0"},
          {"module": "url",     "target": "not-a-url"}
        ]
      }'

batch = [
    {"module": "hash", "target": "9c1f0b6d2ae74318bd50c7a9e6f34182bb0d5e7c94a2f61038de7b5c0a91f2d4"},
    {"module": "package", "target": "requests==2.31.0"},
    {"module": "url", "target": "not-a-url"},
]
results = requests.post(
    BASE + "/api/v1/scans/bulk",
    headers=HEADERS,
    json={"submissions": batch},
    timeout=60,
).json()["results"]

for sent, row in zip(batch, results):
    if row["ok"]:
        print(sent["target"], "queued as", row["scan"]["scan_id"])
    else:
        print(sent["target"], "refused:", row["error"]["message"])

$Batch = @(
    @{ module = "hash";    target = "9c1f0b6d2ae74318bd50c7a9e6f34182bb0d5e7c94a2f61038de7b5c0a91f2d4" }
    @{ module = "package"; target = "requests==2.31.0" }
    @{ module = "url";     target = "not-a-url" }
)
$Body = @{ submissions = $Batch } | ConvertTo-Json -Depth 5

$Results = (Invoke-RestMethod -Method Post -Uri "$Base/api/v1/scans/bulk" `
    -Headers $Headers -ContentType "application/json" -Body $Body).results

foreach ($Row in $Results) {
    if ($Row.ok) { "queued as {0}" -f $Row.scan.scan_id }
    else         { "refused: {0}"  -f $Row.error.message }
}

{
  "results": [
    {"ok": true,  "scan": {"scan_id": 48214, "module": "hash", "status": "queued"}},
    {"ok": true,  "scan": {"scan_id": 48215, "module": "package", "status": "queued"}},
    {"ok": false, "error": {"code": "bad_request",
                            "message": "a url submission needs an http:// or https:// URL"}}
  ]
}

curl -sS "$MWG_BASE/api/v1/scans/48213" \
  -H "Authorization: Bearer $MWG_TOKEN"

scan = requests.get(
    BASE + "/api/v1/scans/48213", headers=HEADERS, timeout=30
).json()["scan"]

print(scan["status"], scan["verdict"], scan["score"])

$Scan = (Invoke-RestMethod -Method Get -Headers $Headers `
    -Uri "$Base/api/v1/scans/48213").scan

"{0} {1} {2}" -f $Scan.status, $Scan.verdict, $Scan.score

{
  "scan": {
    "scan_id": 48213,
    "module": "command",
    "status": "completed",
    "verdict": "malicious",
    "score": 82,
    "tags": {"items": ["activity:evasion", "technique:t1497"], "returned": 2,
             "total": 2, "truncated": false},
    "submitted_at": "2026-08-30T09:14:02.118433+00:00",
    "finished_at": "2026-08-30T09:16:41.902117+00:00",
    "sha256": "0d4a9f6be3c25f18a7c0e9b41d2f8a6c53e7b0149ad6c8f2317be0d54c9a1f7e",
    "size": 58,
    "mime": "text/plain",
    "terminal": true,
    "report_available": true
  }
}

curl -sS "$MWG_BASE/api/v1/scans/48213/report" \
  -H "Authorization: Bearer $MWG_TOKEN"

report = requests.get(
    BASE + "/api/v1/scans/48213/report", headers=HEADERS, timeout=60
).json()["report"]

for ioc in report["iocs"]["items"]:
    print(ioc["type"], ioc["value"])
if report["iocs"]["truncated"]:
    print("cut at", report["iocs"]["returned"], "of", report["iocs"]["total"])

$Report = (Invoke-RestMethod -Method Get -Headers $Headers `
    -Uri "$Base/api/v1/scans/48213/report").report

$Report.iocs.items | ForEach-Object { "{0} {1}" -f $_.type, $_.value }
if ($Report.iocs.truncated) {
    "cut at {0} of {1}" -f $Report.iocs.returned, $Report.iocs.total
}

{
  "report": {
    "module": "file",
    "verdict": {"label": "malicious", "score": 75},
    "static": {
      "yara_matches": {"items": ["IsPE32", "HasRichSignature"], "returned": 2,
                       "total": 2, "truncated": false},
      "signed": false,
      "static_risk_score": 10,
      "import_count": 61
    },
    "dynamic": {
      "platform": "windows",
      "behavior_summary": "Decoded a base64 command line, then fetched and ran a second stage.",
      "network": {"connections": {"items": [], "returned": 0,
                                  "total": 0, "truncated": false}}
    },
    "intel": {"vt_malicious": 0, "lol_match": false},
    "iocs": {
      "items": [{"type": "imphash", "value": "e38062877caac65585afa2d2c3200df4"}],
      "returned": 1, "total": 1, "truncated": false
    },
    "run_integrity": {"failed": false, "reached_sample": null,
                      "cause": "", "note": ""},
    "scan_id": 48213,
    "status": "completed",
    "tags": {"items": ["activity:evasion"], "returned": 1, "total": 1, "truncated": false},
    "submitted_at": "2026-08-30T09:14:02.118433+00:00",
    "finished_at": "2026-08-30T09:16:41.902117+00:00",
    "sha256": "32acc1bc543116cbe2cff10cb867772df2f254ff2634c870aef0b46c4b696fdb",
    "size": 11776,
    "mime": "application/vnd.microsoft.portable-executable"
  }
}

curl -s -G "https://malwagon.com/api/v1/indicators" \
  --data-urlencode "value=evil.example" \
  --data-urlencode "type=domain" \
  -H "Authorization: Bearer $MALWAGON_API_KEY"

digest="9c1f0b6d2ae74318bd50c7a9e6f34182bb0d5e7c94a2f61038de7b5c0a91f2d4"

curl -sS "$MWG_BASE/api/v1/hashes/$digest" \
  -H "Authorization: Bearer $MWG_TOKEN"

digest = "9c1f0b6d2ae74318bd50c7a9e6f34182bb0d5e7c94a2f61038de7b5c0a91f2d4"

found = requests.get(
    BASE + "/api/v1/hashes/" + digest, headers=HEADERS, timeout=30
).json()

print(found["scans"]["total"], "prior analyses")
for row in found["scans"]["items"]:
    print(row["scan_id"], row["verdict"], row["score"])

$Digest = "9c1f0b6d2ae74318bd50c7a9e6f34182bb0d5e7c94a2f61038de7b5c0a91f2d4"

$Found = Invoke-RestMethod -Method Get -Headers $Headers `
    -Uri "$Base/api/v1/hashes/$Digest"

"{0} prior analyses" -f $Found.scans.total
$Found.scans.items | ForEach-Object { "{0} {1} {2}" -f $_.scan_id, $_.verdict, $_.score }

{
  "sha256": "9c1f0b6d2ae74318bd50c7a9e6f34182bb0d5e7c94a2f61038de7b5c0a91f2d4",
  "scans": {
    "items": [
      {"scan_id": 47190, "module": "file", "status": "completed",
       "verdict": "malicious", "score": 88,
       "tags": {"items": ["activity:av-detection"], "returned": 1,
                "total": 1, "truncated": false},
       "submitted_at": "2026-08-19T11:02:44.501992+00:00",
       "finished_at": "2026-08-19T11:06:02.774310+00:00",
       "sha256": "9c1f0b6d2ae74318bd50c7a9e6f34182bb0d5e7c94a2f61038de7b5c0a91f2d4",
       "size": 184320,
       "mime": "application/vnd.microsoft.portable-executable"}
    ],
    "returned": 1,
    "total": 1,
    "truncated": false
  }
}

The report object

A report is a derived summary of one completed scan: four analysis sections, an indicator list, a run-integrity block and the scan's own identity fields.

"dropped_files": {
  "items":     [ ... ],
  "returned":  100,
  "total":     417,
  "truncated": true
}

For what the fields mean in analyst terms, see the glossary and the documentation. Worked examples of finished reports are in the public analyses index.

MCP server

The server speaks JSON-RPC 2.0 over plain HTTP at POST /mcp, with no SSE stream, no session and no initialize handshake. It implements revision 2026-07-28, which is the only version it advertises. This page describes the server. No claim is made here about which MCP clients interoperate with it, and no client has been tested against this endpoint; treat compatibility as something to verify yourself.

Wire rules

One endpoint, one method

POST /mcp. GET and DELETE answer 405 with an Allow header, because this revision has no SSE stream to open and no session to tear down. A request that carries an Origin header is answered 403 unless that origin is one the operator has configured, so this endpoint is for clients that are not browsers.

No handshake, no session

Authentication is per-request bearer, exactly as on the REST API. Every request carries its own protocol version and client capabilities instead of negotiating them once.

One message per body

Batches are not part of this revision. A body must be a single JSON-RPC request or notification, and a notification, meaning a message with no id, is accepted with 202 and no reply.

Two things every request must carry, and both are checked before authentication, so getting them wrong produces a protocol error rather than a permission error.

A mirrored header that disagrees with the body is rejected rather than resolved, so an intermediary routing on the header and this server executing the body can never act on different requests. These are the exact refusals, and each is a JSON-RPC error with an HTTP status to match.

{"jsonrpc": "2.0", "error": {"code": -32020,
  "message": "Header mismatch: MCP-Protocol-Version is required"}, "id": 1}

{"jsonrpc": "2.0", "error": {"code": -32602,
  "message": "Invalid params: _meta must carry io.modelcontextprotocol/clientCapabilities"}, "id": 1}

{"jsonrpc": "2.0", "error": {"code": -32022, "message": "Unsupported protocol version",
  "data": {"supported": ["2026-07-28"], "requested": "2025-11-25"}}, "id": 1}

Methods

Three methods are served, and anything else answers 404 with a method-not-found error.

server/discover

Replaces initialize. Returns the supported protocol versions, the server capabilities (tools only, no resources and no prompts) and usage instructions.

tools/list

The tools this token may see, with their input and output schemas. A token without the submit grant is not shown submit_scan at all.

tools/call

Runs one tool. The result carries both a serialised text block and a structuredContent object, plus an isError flag.

mcp_call() {
  # $1 tool name, $2 arguments as a JSON object
  curl -sS -X POST "$MWG_BASE/mcp" \
    -H "Authorization: Bearer $MWG_TOKEN" \
    -H "Content-Type: application/json" \
    -H "MCP-Protocol-Version: 2026-07-28" \
    -H "Mcp-Method: tools/call" \
    -H "Mcp-Name: $1" \
    -d "{
          \"jsonrpc\": \"2.0\",
          \"id\": 1,
          \"method\": \"tools/call\",
          \"params\": {
            \"name\": \"$1\",
            \"arguments\": $2,
            \"_meta\": {
              \"io.modelcontextprotocol/protocolVersion\": \"2026-07-28\",
              \"io.modelcontextprotocol/clientCapabilities\": {}
            }
          }
        }"
}

VERSION = "2026-07-28"

def mcp_call(name, arguments, rid=1):
    body = {
        "jsonrpc": "2.0",
        "id": rid,
        "method": "tools/call",
        "params": {
            "name": name,
            "arguments": arguments,
            "_meta": {
                "io.modelcontextprotocol/protocolVersion": VERSION,
                "io.modelcontextprotocol/clientCapabilities": {},
            },
        },
    }
    reply = requests.post(
        BASE + "/mcp",
        json=body,
        timeout=60,
        headers={
            "Authorization": HEADERS["Authorization"],
            "MCP-Protocol-Version": VERSION,
            "Mcp-Method": "tools/call",
            "Mcp-Name": name,
        },
    ).json()
    if "error" in reply:
        raise RuntimeError(reply["error"]["message"])
    result = reply["result"]
    if result["isError"]:
        raise RuntimeError(result["structuredContent"]["error"])
    return result["structuredContent"]

$Version = "2026-07-28"

function Invoke-McpTool {
    param([string]$Name, [hashtable]$Arguments)

    $Body = @{
        jsonrpc = "2.0"
        id      = 1
        method  = "tools/call"
        params  = @{
            name      = $Name
            arguments = $Arguments
            _meta     = @{
                "io.modelcontextprotocol/protocolVersion"    = $Version
                "io.modelcontextprotocol/clientCapabilities" = @{}
            }
        }
    } | ConvertTo-Json -Depth 8

    $McpHeaders = @{
        Authorization          = "Bearer $env:MWG_TOKEN"
        "MCP-Protocol-Version" = $Version
        "Mcp-Method"           = "tools/call"
        "Mcp-Name"             = $Name
    }
    $Reply = Invoke-RestMethod -Method Post -Uri "$Base/mcp" `
        -Headers $McpHeaders -ContentType "application/json" -Body $Body

    if ($Reply.result.isError) { throw $Reply.result.structuredContent.error }
    $Reply.result.structuredContent
}

Tools

Five tools, four of them read-only. Each result carries a content array with the serialised JSON and a structuredContent object with the same data parsed, so a client can read whichever it prefers. A scan that does not exist and one this token may not read answer not found identically.

mcp_call lookup_hash \
  '{"sha256": "9c1f0b6d2ae74318bd50c7a9e6f34182bb0d5e7c94a2f61038de7b5c0a91f2d4"}'

found = mcp_call("lookup_hash", {
    "sha256": "9c1f0b6d2ae74318bd50c7a9e6f34182bb0d5e7c94a2f61038de7b5c0a91f2d4",
})
print(found["scans"]["total"], "prior analyses")

$Found = Invoke-McpTool -Name "lookup_hash" -Arguments @{
    sha256 = "9c1f0b6d2ae74318bd50c7a9e6f34182bb0d5e7c94a2f61038de7b5c0a91f2d4"
}
"{0} prior analyses" -f $Found.scans.total

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{"type": "text", "text": "{\"sha256\": \"9c1f...\", ...}"}],
    "structuredContent": {
      "sha256": "9c1f0b6d2ae74318bd50c7a9e6f34182bb0d5e7c94a2f61038de7b5c0a91f2d4",
      "scans": {"items": [], "returned": 0, "total": 0, "truncated": false}
    },
    "isError": false,
    "resultType": "complete",
    "_meta": {"io.modelcontextprotocol/serverInfo": {"name": "sandbox",
                                                     "version": "1.0.0"}}
  }
}

mcp_call get_report '{"scan_id": 48213}'

report = mcp_call("get_report", {"scan_id": 48213})
print(report["verdict"]["label"], report["verdict"]["score"])
for ioc in report["iocs"]["items"]:
    print(ioc["type"], ioc["value"])

$Report = Invoke-McpTool -Name "get_report" -Arguments @{ scan_id = 48213 }
"{0} {1}" -f $Report.verdict.label, $Report.verdict.score
$Report.iocs.items | ForEach-Object { "{0} {1}" -f $_.type, $_.value }

mcp_call search_indicator \
  '{"indicator": "cdn-update[.]example", "type": "domain"}'

hits = mcp_call("search_indicator", {
    "indicator": "cdn-update[.]example",
    "type": "domain",
})
for row in hits["matches"]["items"]:
    print(row["scan_id"], row["verdict"], row["ioc"])

$Hits = Invoke-McpTool -Name "search_indicator" -Arguments @{
    indicator = "cdn-update[.]example"
    type      = "domain"
}
$Hits.matches.items | ForEach-Object { "{0} {1} {2}" -f $_.scan_id, $_.verdict, $_.ioc }

{
  "indicator": "cdn-update[.]example",
  "matches": {
    "items": [
      {"scan_id": 48213, "module": "url", "status": "completed",
       "verdict": "malicious", "score": 82,
       "ioc_type": "domain", "ioc": "cdn-update[.]example"}
    ],
    "returned": 1, "total": 1, "truncated": false
  }
}

mcp_call poll_scan '{"scan_id": 48213}'

import time

while True:
    scan = mcp_call("poll_scan", {"scan_id": 48213})
    if scan["terminal"]:
        break
    time.sleep(10)

do {
    Start-Sleep -Seconds 10
    $Scan = Invoke-McpTool -Name "poll_scan" -Arguments @{ scan_id = 48213 }
} until ($Scan.terminal)

mcp_call submit_scan \
  '{"module": "url", "target": "https://invoice-portal.example/pay", "private": true}'

queued = mcp_call("submit_scan", {
    "module": "url",
    "target": "https://invoice-portal.example/pay",
    "private": True,
})
scan_id = queued["scan_id"]

$Queued = Invoke-McpTool -Name "submit_scan" -Arguments @{
    module  = "url"
    target  = "https://invoice-portal.example/pay"
    private = $true
}
$ScanId = $Queued.scan_id

{
  "scan_id": 48216,
  "module": "url",
  "status": "queued",
  "verdict": null,
  "score": null,
  "tags": {"items": [], "returned": 0, "total": 0, "truncated": false},
  "submitted_at": "2026-08-30T09:22:10.004821+00:00",
  "finished_at": null,
  "sha256": "b19c0f0e8d1a4f2c7e6b5a34d2019f8c6e4b7a1d3f5c9e2b8a4d6f0c1e3b5a79",
  "size": 41,
  "mime": "text/plain",
  "terminal": false,
  "report_available": false
}

Boundaries

These are limits of both surfaces as they stand, not gaps waiting to be filled.

One file per upload, and no upload over MCP

The upload route takes one part named file and refuses a request carrying several, because a scan is one sample. The MCP surface takes no bytes at all. The four text modules are unchanged: a SHA-256, a URL, a command line or a package specifier.

No sample, ever

The API never returns a sample, a download URL, an artifact identifier, a memory dump, a packet capture or decompiled sample source. Reports are derived data, assembled field by field from an allowlist, so a field nobody named cannot appear.

You read your own scans and genuinely public ones

Nothing else is reachable, including scans belonging to other accounts. A scan that does not exist and a scan you may not read give the same answer, so the two cases are not told apart by the response.

No self-service webhooks

There is no endpoint for registering a callback, and no way to create one from the console. Where a webhook is in use, an operator has configured it. Poll the scan id instead; that is what the status route is sized for.

No client compatibility claim

The MCP server implements revision 2026-07-28 as described above. No MCP client has been tested against it, so nothing here should be read as a statement that any particular client will work.

A token is shown once

The raw value exists only in the response that created it and is stored only as a keyed hash. If you lose it, revoke it and mint another.

This page describes the running code

Endpoints, parameters, error codes and rate limits can change. Where this reference and the API disagree, the API is the authority, and the difference is worth reporting through the contact page.