verdictswarm-mcp

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.

uvx verdictswarm-mcp

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.

Tools

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: mcp
• X-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

• VerdictSwarm
• API documentation
• GitHub repository
• Security policy

MIT licensed. See LICENSE.