Skip to main content
Glama
token-verdict-mcp

token-verdict-mcp

token-verdict-mcp

M8ven Score M8ven Score

Standalone home: This server was split out of QuincyGB/token-verdict-tools so each MCP server has its own GitHub repository for directory ingestion and maintenance. The PyPI package name (token-verdict-mcp), version, and install command are unchanged.

An MCP server (stdio transport) that exposes Token Verdict as a native tool for any MCP host — Claude Desktop, Cursor, or your own agent runtime.

Token Verdict is a pay-per-call token risk screen for AI agents: send a token contract address, get back a verdict (SOLID / CAUTION / DANGER), a 0–100 risk score, six weighted market-structure signals explained in plain English, and a written analyst take. It costs $0.02 USDC per call on Base, paid via the x402 protocol — no accounts, no API keys; the payment is the authentication.

The tool

token_verdict — one tool, the service's real contract:

Input

Type

Notes

address

string (required)

Token contract address (0x...)

chain

string, default "base"

base · ethereum · solana — which token market to analyze. Payment always settles in USDC on Base.

Output is the service's verdict JSON: token, verdict, score, signals (exactly six), take, and market (the raw data the verdict derives from, so callers can re-check the math). Market-structure analysis only — honeypot simulation and holder concentration are not checked, and the product says so in every take.

Related MCP server: verdix

Install

pip install token-verdict-mcp

# Or from a checkout of this repository:
pip install .

Requires Python ≥ 3.10. The server pins the MCP v1 SDK API (mcp>=1.2,<2).

Configuration

All configuration is the operator's own environment — whoever runs this server supplies their own wallet. No key material ships in this package, and the package author never sees your key.

Env var

Required

Purpose

AGENT_PRIVATE_KEY

for paid calls

EVM private key (0x...) of a wallet holding USDC on Base. Used locally to sign the x402 EIP-3009 authorization.

AGENT_KEY_FILE

alternative

Path to a file containing that key.

TOKEN_VERDICT_URL

no

Service base URL override (default: production).

TOKEN_VERDICT_MAX_AMOUNT_UNITS

no

Spend guard per call in USDC micro-units (default 20000 = $0.02, the known price). The client refuses to sign anything priced above it.

Without a signer configured the tool never pays. On a 402 it returns the parsed challenge as a structured error — error: "payment_required" with the full accepts array (scheme, network, asset, amount, payTo) — so the calling agent can see the price and decide what to do, or settle the challenge with its own x402 client.

MCP host configuration

Claude Desktop (claude_desktop_config.json) — same shape for other stdio MCP hosts:

{
  "mcpServers": {
    "token-verdict": {
      "command": "token-verdict-mcp",
      "env": {
        "AGENT_PRIVATE_KEY": "0xYOUR_OWN_WALLET_KEY"
      }
    }
  }
}

From a checkout instead of an install:

{
  "mcpServers": {
    "token-verdict": {
      "command": "python",
      "args": ["-m", "token_verdict_mcp"],
      "env": {
        "PYTHONPATH": "/path/to/token-verdict-mcp/src",
        "AGENT_KEY_FILE": "/path/to/your/agent.key"
      }
    }
  }
}

Prefer AGENT_KEY_FILE over inlining a key in a config file when your host setup allows it.

How payment works

The client mirrors the standard x402 v2 flow (the same flow used for the service's own live cataloging payment):

  1. POST /v1/verdict unpaid → HTTP 402, challenge base64-encoded in the payment-required header.

  2. Pick the exact / eip155:8453 entry from accepts.

  3. Build an EIP-3009 TransferWithAuthorization (validAfter: 0, validBefore: now + maxTimeoutSeconds, random 32-byte nonce) and sign it as EIP-712 typed data against the USDC domain the challenge advertises (extra.name / extra.version).

  4. Retry the identical POST with the payload in the PAYMENT-SIGNATURE header. The service verifies and settles through its facilitator (PayAI) server-side; the settlement receipt comes back in the payment-response header.

Tests

pip install -e ".[dev]"
pytest

14 tests, all payments mocked (httpx MockTransport, throwaway signer generated at test time). The 402 fixture is the real challenge captured from production; the paid-flow test verifies the EIP-712 signature actually recovers to the signer address.

Security notes

  • Your private key is read from your environment at runtime and used only to sign payment authorizations locally. It is never transmitted — the x402 payload contains a signature, not a key.

  • The spend guard caps any single call at the configured amount (default: exactly the $0.02 price).

  • Run this with a dedicated agent wallet holding only working funds, the same way you would fund any agent.

Available Tools

1 tool
token_verdictA

Get a risk verdict for a token before buying, swapping, or routing funds into it.

Calls Token Verdict (POST /v1/verdict, $0.02 USDC on Base via x402).
Returns verdict (SOLID / CAUTION / DANGER), a 0-100 risk score, six
weighted market-structure signals (liquidity depth, volume churn,
sell pressure, price action, trader breadth, pair age), a written
analyst take, and the raw market data the verdict derives from.

Args:
    address: Token contract address (0x...).
    chain: Chain label — "base" (default), "ethereum", or "solana".

Inputs: address (required), chain. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 1 tool

    Disambiguation5/5

    There is only one tool, so there is no possibility of selecting the wrong one. Its purpose—fetching a pre-trade risk verdict for a token address—is stated unambiguously.

    Naming Consistency4/5

    The name token_verdict uses clean snake_case and mirrors the backing service name, but it is a noun phrase rather than the verb_noun pattern typical of action-oriented tool sets. With only one tool there is no inconsistency to speak of, just a minor stylistic deviation.

    Tool Count3/5

    The server wraps a single paid x402 endpoint ($0.02 USDC per call), so one tool is defensible and each tool does earn its place. However, a one-tool surface is thin and sits at the borderline of the 1-2 tool range.

    Completeness4/5

    For the narrow stated purpose—pre-trade risk assessment—the tool returns everything needed: verdict, 0-100 score, six weighted signals, analyst commentary, and raw market data. Minor gaps exist (no batch/multi-token lookup, no way to enumerate supported chains beyond the description), but agents can work around these with the documented chain argument.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables MCP-capable AI agents to make pay-per-call Solana data requests (snapshots, risk checks, token reports, health, balances, transactions, trending pairs) with automatic USDC settlement over x402.
      5
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to check an EVM address on Base for risk (safe, caution, danger) before sending funds, with reasons, paid per call via x402 from the user's own wallet.
      7
      135 npm
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to call pay-per-call x402 endpoints on Base mainnet using the caller's own USDC wallet, covering single and batch token risk checks, the latest BTC radar signal, project info, and a free health probe. Payments are EIP-3009 signed with a configurable per-call spending cap, and any quote with an unexpected payee, network, or asset is refused before payment.
      5
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to access pay-per-call onchain and URL safety APIs over MCP, covering transaction explanations, token approval checks, address inspection, contract risk heuristics, URL safety, gas snapshots, ENS resolution, calldata decoding, and wallet portfolio data. Payments are handled per call in USDC on Base via x402, with no signup or API key required.
      1
      MIT