VirusTotal AI

Connect once. Investigate when it matters.

Give your agent threat intelligence.

Check a download before running it. Investigate an unfamiliar link. Submit an authorized file and follow its analysis — with VirusTotal evidence in your agent’s workflow.

Free VTAI access. No VirusTotal API key needed for basic use. Keep your existing client login; model-provider accounts and charges are separate.

1. Choose your client

2. Set up free access

VTAI credential

Keep using your protected credential file. Continue to the configuration below; reconnecting does not require another registration.

Save a downloaded credential securely

On macOS or Linux, adjust your Downloads path if necessary. The destination must not already exist.

(
  set -eu
  install -d -m 700 "$HOME/.config/vt-mcp"
  test ! -e "$HOME/.config/vt-mcp/token"
  test ! -L "$HOME/.config/vt-mcp/token"
  install -m 600 "$HOME/Downloads/vtai-token.txt" "$HOME/.config/vt-mcp/token"
)

A browser cannot verify the saved file or its permissions. Once the protected copy exists, remove the extra download. If a credential already exists, keep it or choose another path and update the configuration. On Windows, use Windows access permissions; these POSIX commands do not apply.

Keep credentials out of prompts, tool arguments and URLs. Store them in protected files or your client’s credential settings.

3. Connect your client

Install the local server · Python 3.12+ and uv

This downloads the wheel from the public release, verifies its pinned SHA-256 and installs it with uv. Requires Python 3.12+, curl and uv on macOS or Linux.

(
  set -eu
  vt_mcp_install_dir=$(mktemp -d)
  trap 'rm -rf "$vt_mcp_install_dir"' EXIT
  cd "$vt_mcp_install_dir"
  curl --fail --location --max-time 60 --connect-timeout 10 --proto '=https' --proto-redir '=https' \
    --output vt_mcp-0.8.0-py3-none-any.whl \
    https://github.com/king-tero/vt-mcp/releases/download/v0.8.0/vt_mcp-0.8.0-py3-none-any.whl
  python3 - <<'PY'
import hashlib
from pathlib import Path
wheel = Path("vt_mcp-0.8.0-py3-none-any.whl")
if hashlib.sha256(wheel.read_bytes()).hexdigest() != "25fe939fbbcda056acb7780ce75f7a8651f9628ada1c1c6887ab5ce20b3e300c":
    raise SystemExit("Checksum mismatch; installation stopped.")
print("Wheel checksum verified.")
PY
  uv tool install --python 3.12 ./vt_mcp-0.8.0-py3-none-any.whl
  uv tool update-shell
)

Open a fresh terminal after updating PATH. If the client cannot find vt-mcp, set its absolute executable path in the configuration. The package is distributed through the release, not PyPI.

Merge into ~/.copilot/mcp-config.json, preserving other servers and settings.

{
  "mcpServers": {
    "virustotal": {
      "type": "local",
      "command": "vt-mcp",
      "env": {
        "VTAI_TOKEN_FILE": "~/.config/vt-mcp/token",
        "VTAI_BASE_URL": "https://ai.virustotal.com/api/v3"
      },
      "args": [],
      "tools": [
        "*"
      ],
      "timeout": 180000
    }
  }
}

Restart Copilot CLI and inspect copilot mcp get virustotal. The tools list controls availability; Copilot permissions control execution. Your Copilot login is separate from VTAI access. Configuration recognition was checked with Copilot CLI 1.0.83.

Domain lookup verified with a model through local stdio; other tool workflows remain unverified.

Use the activation steps for your selected client above to discover the VirusTotal tools. Downloaded configurations contain references, not credentials; merge them into your existing settings.

Authentication and host permissions

Use your existing client login; VTAI access is separate. This token setup does not provide OAuth. Remote MCP accepts the same VTAI Agent Token using x-apikey or Authorization: Bearer; send one, not both. A hosted connector that requires OAuth needs a separate integration.

Agy uses local stdio for this setup. Configure your client’s tool permissions for the authorized task. The submission tools have no per-call confirmation or consent argument; host permissions still apply. See the client guide.

4. Make your first tool call

Ask your agent: “Use VirusTotal to check virustotal.com. Show the source, analysis date, coverage and report link.” Confirm it calls get_domain_report. This uses one query and does not submit a file.

Available tools and a browser access check

Your client should list get_file_report, get_url_report, get_domain_report, get_ip_report, get_analysis, submit_file and get_submission. Local stdio adds submit_local_file, for eight tools.

The optional check below reads the empty-file hash from the VTAI report API. It uses shared query quota, including for an unknown report or upstream failure. It does not verify your MCP client or model, upload a file or automatically retry.

Submit a file and recover its analysis

For content authorized for standard public sharing, submit_local_file(path, expected_sha256=None) accepts at most 32,000,000 bytes over stdio. It copies the file accessible to the local vt-mcp process; the optional SHA-256 must match that copy.

submit_file(sha256, content_base64) accepts at most 24,000,000 decoded bytes over HTTP or stdio. HTTP receives bytes; it cannot read a path on your machine. Base64 passes through your MCP host and may be retained by your model provider. Standard submission is not confidential: content may be accessible to the VirusTotal community and security partners.

Keep the SHA-256. Recover an uncertain result with get_submission(sha256) on the same account, without sending the file again. exists returns an existing report; submitted supplies an analysis ID. Read it with get_analysis within a finite polling budget. A submission can remain unknown permanently; do not repeat submission to resolve it.

Access limits and interpreting reports

REST and MCP share 60 admitted queries per fixed 60-second window and 1000 per UTC day, per agent. Unknown reports and upstream failures still consume admitted queries. Provider limits may also apply.

A missing report or absence of detections does not establish safety. URL lookup discloses the complete URL to VTAI and VirusTotal. Use a domain lookup when paths, query parameters or fragments contain private information. Report tools and selected-analysis reads do not submit files.

Connection problems and direct API access

For 401 or 403, check credential validity and the client’s environment, input or file mapping without displaying its value. For 400, check malformed or conflicting authentication headers. For 429, respect the supplied retry delay. A service failure is not an unknown report; a missing /mcp endpoint is a connection problem.

Prefer direct HTTP? Use the same token with https://ai.virustotal.com/api/v3. Read the agent API instructions or interactive API docs. Registration is POST /api/v3/agents/register; reconnecting does not require another registration.

Disconnect a client

Remove or disable the virustotal entry, restart the client and confirm the tools disappear. Other clients using the same credential retain access. Remove stored credentials only when no client needs them. Reconnect with the same credential while it remains active. VTAI history is retained.

Revoke this credential everywhere

Revoking the credential disables this agent’s access through REST and MCP in every client. Existing records remain. A query admitted before revocation may finish.

Keep your protected copy if revocation is not confirmed, so you can try again.