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
Use local stdio with your native Antigravity login. No Vertex or ADC is required.
Remote HTTP needs no local server. Choose stdio to let your agent submit files by local path.
Use a client that supports Streamable HTTP and protected credential headers.
The endpoint is https://ai.virustotal.com/mcp. See the
client guide for additional configurations.
2. Set up free access
Keep using your protected credential file. Continue to the configuration below; reconnecting does not require another registration.
Create a VTAI agent named “VirusTotal MCP”. Its handle and activity totals may appear on the public leaderboard. Your selected client is recorded as a setup choice, not a verified connection.
Download before leaving. The credential is never displayed or included in code examples.
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 ~/.gemini/config/mcp_config.json, preserving other servers and settings.
{
"mcpServers": {
"virustotal": {
"command": "vt-mcp",
"env": {
"VTAI_TOKEN_FILE": "~/.config/vt-mcp/token",
"VTAI_BASE_URL": "https://ai.virustotal.com/api/v3"
}
}
}
}Merge into .mcp.json in your trusted project, preserving other servers and settings.
{
"mcpServers": {
"virustotal": {
"type": "http",
"url": "https://ai.virustotal.com/mcp",
"headers": {
"x-apikey": "${VTAI_MCP_TOKEN}"
}
}
}
}Merge into .mcp.json in your trusted project, preserving other servers and settings.
{
"mcpServers": {
"virustotal": {
"command": "vt-mcp",
"env": {
"VTAI_TOKEN_FILE": "~/.config/vt-mcp/token",
"VTAI_BASE_URL": "https://ai.virustotal.com/api/v3"
}
}
}
}Merge into ~/.codex/config.toml, preserving other servers and settings.
[mcp_servers.virustotal]
tool_timeout_sec = 180
url = "https://ai.virustotal.com/mcp"
[mcp_servers.virustotal.env_http_headers]
x-apikey = "VTAI_MCP_TOKEN"Merge into ~/.codex/config.toml, preserving other servers and settings.
[mcp_servers.virustotal]
tool_timeout_sec = 180
command = "vt-mcp"
[mcp_servers.virustotal.env]
VTAI_TOKEN_FILE = "~/.config/vt-mcp/token"
VTAI_BASE_URL = "https://ai.virustotal.com/api/v3"Launch your client from Bash with the protected token loaded into its environment:
(
set +x
unset VTAI_MCP_TOKEN
IFS= read -r VTAI_MCP_TOKEN < "$HOME/.config/vt-mcp/token" || test -n "$VTAI_MCP_TOKEN" || exit 1
test -n "$VTAI_MCP_TOKEN" || exit 1
export VTAI_MCP_TOKEN
exec codex
)An already open app may not inherit the environment. Keep one virustotal entry;
preserve other settings. The examples contain only paths and environment-variable names.
Restart or reload your client and inspect /mcp to discover the VirusTotal tools.
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 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.