# VerdictSwarm MCP Server

<!-- 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).