token-verdict-mcp
[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:
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.
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.
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:
From a checkout instead of an install:
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):
POST /v1/verdict unpaid → HTTP 402, challenge base64-encoded in the
payment-required header.- Pick the
exact / eip155:8453 entry from accepts.
- 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).
- 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
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.
