Troubleshooting

Work through Verify your setup first. It isolates which layer is broken in four commands, and most of what follows assumes you know that.

The tools do not appear at all

You reloaded instead of restarting. Nearly every client reads MCP config once at launch and caches the tool list. Quit the application fully and reopen it. In Claude Desktop, closing the window is not quitting.

The JSON is invalid. A trailing comma, or a smart quote from copying out of a web page. Run the file through jq ., because most clients fail silently on a parse error instead of telling you.

Wrong key name for your client. These differ and are not interchangeable:

Windsurf and Goose account for most of these reports.

Wrong file. Several clients have both a user and a project config, and edits to the wrong one look identical to no edit at all.

Every tool returns 401

The header is missing the organisation half. It must be:

Authorization: ApiKey <orgId>:<hex>

Both halves, separated by a colon. The CLI stores only the hex internally, so a value copied from ~/.vulnetix/credentials.json is half of what the header needs. If you used vulnetix_auth_poll, it hands you the complete value.

The variable was not expanded. If results contain the literal ${VULNETIX_KEY}, the client never saw your shell environment. That is common when the app was launched from a desktop icon instead of a terminal. Use a user-scoped config with a literal value (it is outside git anyway), or your client’s inputs mechanism.

The key was rotated or revoked. Confirm with vulnetix_auth_status.

-32602 Invalid _meta envelope

You are hand-crafting requests and one of the three required _meta keys is missing:

"_meta": {
  "io.modelcontextprotocol/protocolVersion": "2026-07-28",
  "io.modelcontextprotocol/clientInfo": { "name": "x", "version": "1" },
  "io.modelcontextprotocol/clientCapabilities": {}
}

Envelope validation runs before version negotiation, so a request with both a bad version and an incomplete envelope reports the envelope. The error names the missing key.

-32020 Header mismatch

Mcp-Name or Mcp-Method disagrees with the body. When calling vulnetix_vuln, Mcp-Name must be exactly vulnetix_vuln. Real client SDKs get this right; it only appears when hand-crafting.

-32022 Unsupported protocol version

The data.supported array lists what the server speaks. If your client sent something older and did not retry, it is not handling the corrective. Most client SDKs default to the legacy era, which the server does serve, so seeing this usually means a hand-built request.

An exploit or IOC list is empty

Check gated and the count before concluding anything.

{ "exploitCount": 19868, "exploitsBySource": [], "note": "...tier gating, not an absence of exploits..." }

Records are gated on Community; counts are not. An empty list with a non-zero count means withheld, not absent. vulnetix_exploits, vulnetix_iocs, vulnetix_sightings and vulnetix_threat_actors all behave this way and all say so in the response.

“Do NOT retry this call”

Your daily quota is exhausted. The message carries the reset time. Retrying cannot succeed and only burns budget. The wording is aimed at your agent, which will otherwise try again immediately.

See Plans & limits.

A tool times out

The API runs on AWS behind a CDN while the server runs at the edge, so a cold call against a large index can take several seconds. The server allows 45.

If your client times out first, raise its timeout. Goose defaults low enough to cut off a first call. Retry usually succeeds immediately from the edge cache.

The agent has the tools but never uses them

Wrong mode. Most clients only call MCP tools in an agent mode: Cursor’s Agent, VS Code’s Agent, Continue’s Agent, Cline’s Act. Inline edit and plain chat do not.

Tool budget exceeded. Clients cap how many tools they send to the model (Cursor historically ~40–50, VS Code 128). Vulnetix contributes 31, so several servers together can push you over and tools are dropped silently. Disable servers you are not using.

The model does not support tool calling. Continue in particular will list tools it cannot route to.

Results look truncated

By design. See Response shaping. Check _meta["vulnetix/shaping"]. If you need the enumeration, pass detail: "full" on vulnetix_vuln, or use vdb_request for the unshaped endpoint.

Stale answers

Responses are edge-cached per organisation, 5–60 minutes depending on the tool. _meta["vulnetix/upstream"].cached tells you when a result came from cache. For a fresh read, use vdb_request with different query parameters, which produces a different cache key.

Connection works, then stops

There is no session to expire, so this is not the server dropping you. Check whether the key was rotated, and whether a corporate proxy is intercepting TLS intermittently.

Still stuck

Open an issue with your client and version, the redacted config block, and the exact error. _meta from a failing result is the most useful thing you can include.