Instructions for agents (Markdown)
Connect once. Investigate when it matters.
Connect Cursor to VirusTotal
Cursor CLI discovery and token expansion verified locally; IDE, tool calls and model workflow pending.
Check a download before running it. Investigate an unfamiliar link. Analyze files and URLs, or rescan domains and IPs — with VirusTotal evidence in your agent’s workflow.
Free VTAI access within the published quotas. No VirusTotal API key needed. 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. Run setup once
Copy this block into your terminal. It reuses your VTAI credential or creates free access, stores it locally and connects the selected client. Other client settings stay in place.
Inspect or download setup.py · Install uv for stdio
Existing tokens and what setup changes
The installer uses ~/.config/vt-mcp/token. If your credential is elsewhere, add
--token-file /path/to/token to the Python command. Its value stays out of commands and URLs.
New access creates a VTAI agent whose handle and activity totals may appear on the public leaderboard. Setup changes this client’s user configuration and keeps credentials in files restricted to your account. Claude Code and Codex HTTP read the protected token automatically through a local helper. For stdio, uv runs the official pinned PyPI package. Existing incompatible entries are reported before creating access.
Reconnect using the same credential. An uncertain registration is not retried automatically. If a project already configures VirusTotal, it may take precedence over the user configuration.
2. Connect your editor
Already have an Agent Token? Reuse it. Otherwise, create free access below.
Confirm installation, then paste your VTAI credential into VS Code’s password prompt. The link contains only configuration; your token stays out of the URL. This uses the local Extension Host. Servers with password inputs are not forwarded to the Agent Host. If the link cannot open your editor, use the configuration below.
This imports the configuration only. Load VTAI_MCP_TOKEN into the editor’s environment using
the instructions below before connecting. The link contains no credential; a button click does not verify access.
Open Cascade’s MCP settings and its raw configuration file. The recipe below reads your protected token file; merge it with your existing servers, then refresh the tool list. There is no verified browser OAuth recipe for Cascade; use the Agent Token setup below. Native VTAI tool calls in Cascade remain unverified.
Set up your Agent Token and client
Reuse your existing Agent Token, or create one below. Then add the configuration for your selected client.
Reuse or create 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.
Configure your client manually
First, install the local server
Install the official vt-mcp 0.9.9 package from PyPI. Requires uv; it can provision Python 3.12 when needed.
uv tool install --python 3.12 vt-mcp==0.9.9 && uv tool update-shellOpen a fresh terminal after updating PATH. If the client cannot find vt-mcp, set its absolute executable path
in the configuration.
Merge into ~/.cursor/mcp.json or .cursor/mcp.json in your trusted project, preserving other servers and settings.
{
"mcpServers": {
"virustotal": {
"url": "https://ai.virustotal.com/mcp",
"headers": {
"Authorization": "Bearer ${env:VTAI_MCP_TOKEN}"
}
}
}
}Close an existing Cursor GUI before launching it with the protected environment below. Replace the executable if needed, or use exec agent for Cursor CLI. Enable virustotal in MCP settings. For CLI discovery, reuse the launch block with exec agent mcp list or exec agent mcp list-tools virustotal so each check loads the same protected token.
Cursor CLI discovery and token expansion verified locally; IDE, tool calls and model workflow pending.
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 cursor
)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.
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. For browser sign-in, choose a supported OAuth recipe from the connection guide.
Remote MCP accepts the same VTAI Agent Token using x-apikey or Authorization: Bearer;
send one, not both.
This Agent Token recipe uses the selected connection type. 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.
Make your first tool call
Ask your agent: “Use VirusTotal to get the domain report for 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, get_submission,
submit_url, reanalyze_domain and reanalyze_ip.
Local stdio adds submit_local_file, for local file paths. Remote MCP also lists submit_attachment
for attachment descriptors with a public HTTPS download_url; file_id, file_name and mime_type are optional.
The client must supply the original file's URL; never invent one. Native attachment availability depends on the client.
The optional check below validates your Agent Token without spending query quota. It does not check remaining quota, upstream availability or your MCP client, and does not automatically retry.
Submit a file and recover its analysis
Submit actual bytes only when the user explicitly requests the upload, under the sharing guidance above.
A missing report is not permission to upload. 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.
If this client cannot transfer the file bytes for an explicitly requested upload, offer the existing VirusTotal upload page at https://www.virustotal.com/gui/home/upload under the same sharing guidance. Before uploading, manually check the file's actual hash in VirusTotal and upload only if unknown. After the user uploads the file, obtain its actual hash and look up its report. The report may not be available immediately; every repeated query consumes quota. A web upload creates no VTAI receipt. This alternative does not bypass client permissions, authentication or quota limits, and must not repeat an uncertain submission.
For submissions through this connection, keep the SHA-256. Recover an uncertain result with get_submission(sha256) using the same connection or credential,
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.
Analyze a URL, domain or IP address
Only when the user explicitly requests URL submission or network reanalysis, use submit_url(url, request_id), reanalyze_domain(domain, request_id) or
reanalyze_ip(ip, request_id). Generate and persist a canonical lowercase UUIDv4 request ID before
calling. These operations use standard VirusTotal sharing without a per-operation confirmation from VTAI.
After an uncertain response, recover with get_submission(request_id=request_id) using the same
connection. Supply exactly one of sha256 or request_id. Read the returned analysis with
get_analysis(analysis_id, request_id=request_id) within a finite polling budget. Do not automatically
replay the POST; an intentional later rescan uses a new request ID.
OAuth requires vt:reports:read and vt:network-analysis:write.
An existing file permission does not authorize network analysis. Reconnect and approve the new permission
once for that connection; Agent Tokens retain their task-authorized capabilities.
Access limits and interpreting reports
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 Retry-After and keep
the existing credential; registering another identity is not quota recovery.
A service failure is not an unknown report; a missing /mcp endpoint is a connection problem.
A tool's not_found is unknown, not evidence of safety. Only when the user explicitly requests an upload,
submit actual bytes with the existing file tools; a hash cannot start analysis. Network submissions and reanalysis
also require the user's explicit request; retain the request ID for recovery.
X-VTAI-Error: unexpanded_credential means an x-apikey variable reference
was sent literally. Load the protected token into the client environment and use its documented variable syntax.
Do not paste the token into chat or register again. This specific diagnostic applies to x-apikey.
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.
Free access, shared protection
Free quota: 60 queries per 60 seconds and 1,000 per UTC day per Agent Token or OAuth account; repeats, cached reports and unknown hashes count. Uploading a new file uses no query quota and is limited to 20 per minute and 500 per day. Creating extra identities to avoid limits is not permitted.
Submissions are shared with the VirusTotal community and partners. Upload files, submit URLs or request network reanalysis only when the user explicitly requests that action.
Full access limits and sharing policy
Query limits: 60 admitted queries per fixed 60-second window and 1000 per UTC day. Agent Tokens share the agent's allowance across REST and MCP; OAuth connections share the account's allowance. Unknown reports and upstream failures after admission count. Every repeated lookup counts again, including cached reports and hashes with no report. On 429, honor Retry-After and reuse your credential. File submissions first check whether the hash exists in VirusTotal. Only confirmed unknown files are uploaded, without using query quota, even when the query allowance is exhausted. A separate file contribution limit permits 20 admitted upload attempts per fixed 60-second window and 500 per UTC day, per Agent Token identity or OAuth account across connections. Failed or uncertain admitted attempts still count; known files and receipt recovery do not. Creating multiple identities or accounts to evade limits is not permitted. If the file is known, returning its existing report costs one query and no file is uploaded. Explicit hash lookups and analysis-result reads still count. The access check costs no query quota and does not report remaining quota.
Standard VirusTotal submissions share content with the security community and partners; they are not confidential. Upload files or attachments, submit URLs, or request domain/IP reanalysis only when the user explicitly requests that action. A missing report, an unfamiliar file or a suspicious indicator is not permission to submit it. Explain the sharing and ask before submitting the user's own documents, internal code, credentials or personal data. Submission tools add no per-call confirmation; client permissions still apply.