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.0

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.