VerdictSwarm MCP Server
VerdictSwarm is a pre-trade security layer for agents that touch crypto. This MCP server exposes the Verdict API v2 as a small set of read-only tools for token checks, size-aware exit screening, and live pricing discovery.
Quick start
No account setup is required. If VS_API_KEY is absent, the server mints a free key on the first API-backed tool call and saves it in the platform user config directory.
Then ask your MCP client: “Check DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 on Solana at fast level.”
To supply an existing free or credits-backed key:
VS_API_KEY=vs1_your_key uvx verdictswarm-mcp
Claude Desktop, Cursor, Windsurf, and OpenClaw
Use this server entry (the env block is optional):
{
"mcpServers": {
"verdictswarm": {
"command": "uvx",
"args": ["verdictswarm-mcp"],
"env": {
"VS_API_KEY": "vs1_your_key"
}
}
}
}
Without VS_API_KEY, the self-provisioned key is stored at:
- macOS:
~/Library/Application Support/VerdictSwarm/config.json
- Linux:
${XDG_CONFIG_HOME:-~/.config}/verdictswarm/config.json
- Windows:
%APPDATA%\VerdictSwarm\config.json
The file is created with user-only permissions where the operating system supports them. Set VS_CONFIG_DIR to override the directory.
| Tool | Description |
|---|
check_token(address, chain="solana", level="fast") | Calls POST /v2/verdict and returns action, score, summary, and the five strongest signals. Levels are triage, fast, and deep. |
exit_sim(address, size_usd, side) | Requests include:["exit_sim"] and returns the fresh Solana exit-simulation block. Side is buy or sell. |
get_pricing() | Reads live pricing, levels, limits, and supported chains from GET /v2/verdict/info. |
The 0.1.x names scan_token, get_quick_score, check_rug_risk, get_token_report, and verify_payment are no longer advertised as MCP tools; clients see only the three current v2 tools above. An explicit call to an old name still returns a migration response and makes no legacy pay-lane request.
Free quota and x402 overflow
Free keys have per-level daily limits advertised by the API. If a limit is exhausted, the tool response says when the quota resets and preserves the complete x402 challenge. To continue immediately, set VS_API_KEY to a credits-backed key or use the returned x402 payment instructions.
The MCP client sends these attribution headers on API requests:
X-VS-Integration: mcpX-VS-SDK-Version: 0.2.1
Configuration
| Environment variable | Default | Description |
|---|
VS_API_KEY | unset | Optional free or credits-backed v2 API key. |
VS_API_URL | https://api.vswarm.io | VerdictSwarm API base URL. |
VS_TIMEOUT | 120 | HTTP request timeout in seconds. |
VS_CONFIG_DIR | platform user config dir | Directory for the self-provisioned key. |
VS_TRANSPORT | stdio | MCP transport. Use streamable-http for HTTP. |
HOST | 0.0.0.0 | HTTP bind host. |
PORT | 8000 | HTTP bind port. |
For HTTP transport:
VS_TRANSPORT=streamable-http HOST=0.0.0.0 PORT=8000 uvx verdictswarm-mcp
Programmatic client
import asyncio
from verdictswarm_mcp import VerdictSwarmApiClient
async def main():
client = VerdictSwarmApiClient()
verdict = await client.check_token("TOKEN_ADDRESS", "solana", "fast")
print(verdict["verdict"]["action"], verdict["verdict"]["score"])
asyncio.run(main())
Development
git clone https://github.com/sentien-labs/verdictswarm-mcp.git
cd verdictswarm-mcp
uv sync --extra dev
uv run --extra dev python -m pytest -q
The server supports Python 3.10–3.13 and both stdio and HTTP transports.
Links
MIT licensed. See LICENSE.