# VerdictSwarm MCP Server

> **Retired October 7, 2026.** The hosted VerdictSwarm API and MCP service are decommissioned. The published package depends on that retired API and no longer provides token checks, free keys, live pricing, or payment services. This repository preserves the implementation for reference and reuse under its existing license. The setup instructions below describe the former service.

<!-- mcp-name: io.github.sentien-labs/verdictswarm-mcp -->

[![PyPI](https://img.shields.io/pypi/v/verdictswarm-mcp)](https://pypi.org/project/verdictswarm-mcp/)
[![Python](https://img.shields.io/badge/python-3.10+-blue)](https://github.com/sentien-labs/verdictswarm-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-1.0-blue)](https://modelcontextprotocol.io)

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.

```bash
uvx verdictswarm-mcp
```

Then ask your MCP client: “Check `DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263` on Solana at fast level.”

To supply an existing free or credits-backed key:

```bash
VS_API_KEY=vs1_your_key uvx verdictswarm-mcp
```

### Claude Desktop, Cursor, Windsurf, and OpenClaw

Use this server entry (the `env` block is optional):

```json
{
  "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:

```bash
VS_TRANSPORT=streamable-http HOST=0.0.0.0 PORT=8000 uvx verdictswarm-mcp
```

## Programmatic client

```python
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

```bash
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.

## Feedback and community

Used the server in an agent, bot, wallet, or dashboard? Share the client,
runtime, where the risk check fits, and what worked or failed through the
[VerdictSwarm community page](https://www.vswarm.io/community?utm_source=github&utm_medium=repository&utm_campaign=community_proof_v1&utm_content=verdictswarm-mcp).
You can also [show an integration](https://github.com/sentien-labs/verdictswarm-mcp/discussions/categories/show-and-tell),
[choose a structured issue form](https://github.com/sentien-labs/verdictswarm-mcp/issues/new/choose),
or add your project to [ADOPTERS.md](ADOPTERS.md). Praise is never required.
Stars should come only from people who independently find the project useful;
agents must not automate them.

## Links

- [VerdictSwarm](https://www.vswarm.io)
- [API documentation](https://api.vswarm.io/docs)
- [GitHub repository](https://github.com/sentien-labs/verdictswarm-mcp)
- [Security policy](SECURITY.md)

MIT licensed. See [LICENSE](LICENSE).