ListSmith MCP
ListSmith MCP lets an MCP host grade and repair x402 service Bazaar discovery metadata via paid ListSmith endpoints.
Use
list_gradeto diagnose one x402 route from itsresource_url, with optionalsample_output; returns reachability, x402 validity, SDK validation, schema quality, defects with severities, 0–100 score, andfix_available.When
sample_outputis supplied to grading, it is also checked against the endpoint’s published output schema.Use
list_fixto repair one route from requiredresource_urlandsample_output, with optionalnameandcategory; returns a repaired discovery package only if it passes both x402 SDK validators.Repairs include a generated description, repaired Bazaar extension, OpenAPI and well-known snippets, instructions, validation results, notes, score before, and defects.
Calls are paid per use in USDC on Base via x402, using the operator’s wallet key/key file and per-route spend guards; without a signer, tools return a structured
payment_requiredchallenge instead of paying.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ListSmith MCP grade the discovery metadata for https://api.example.com/x402/price"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
list-smith-mcp
Standalone home: This server was split out of
QuincyGB/token-verdict-toolsso each MCP server has its own GitHub repository for directory ingestion and maintenance. The PyPI package name (list-smith-mcp), version, and install command are unchanged.
An MCP server (stdio transport) that exposes ListSmith as native tools for any MCP host — Claude Desktop, Cursor, or your own agent runtime.
ListSmith grades and repairs the Bazaar discovery metadata of x402
services. /v1/grade ($0.10) itemizes what is broken in a route's
discovery metadata — hollow schemas, failed SDK validation,
over-500-char descriptions, wrong asset addresses. /v1/fix
($0.50) returns a repaired, validator-passed discovery package inferred
from one real sample output. Both are paid in USDC on Base via the
x402 protocol — no accounts, no API keys; the
payment is the authentication.
The tools
list_grade — diagnosis only, no repaired content:
Input | Type | Notes |
| string (required) | Full URL of the x402 resource to grade |
| any (optional) | One real response body from the endpoint; when supplied, it is also checked against the endpoint's published output schema |
Output: resource_url, graded_at, reachable, http_status,
x402_valid, terms, extension_present, sdk_validation,
schema_quality, defects (with severities), score (0–100), and
fix_available.
list_fix — the repair:
Input | Type | Notes |
| string (required) | Full URL of the x402 resource to repair |
| any (required) | One real response body from the endpoint. The repaired output schema is inferred from this sample only — nothing is invented |
| string (optional) | Display name for the generated description; derived from the URL when omitted |
| string (optional) | Category (e.g. token-risk, search, data, media, monitoring) used to phrase the description's use-when sentence |
Output: resource_url, graded_at, ok, failure, score_before,
defects, package (description, repaired Bazaar extension, OpenAPI
and well-known snippets, instructions, validation results — shipped
only if it passes both x402 SDK validators), and notes.
Related MCP server: a2a-x402-mcp-services
Install
pip install list-smith-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 |
| for paid calls | EVM private key ( |
| alternative | Path to a file containing that key. |
| no | Service base URL override (default: production). |
| no | Spend guard for |
| no | Spend guard for |
Each route is capped at its own price — the client refuses to sign
anything above the route's guard. Without a signer configured the
tools never pay. On a 402 they return 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": {
"list-smith": {
"command": "list-smith-mcp",
"env": {
"AGENT_PRIVATE_KEY": "0xYOUR_OWN_WALLET_KEY"
}
}
}
}From a checkout instead of an install:
{
"mcpServers": {
"list-smith": {
"command": "python",
"args": ["-m", "list_smith_mcp"],
"env": {
"PYTHONPATH": "/path/to/list-smith-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 fleet's own live cataloging payments):
POST /v1/gradeor/v1/fixunpaid → HTTP 402, challenge base64-encoded in thepayment-requiredheader.Pick the
exact/eip155:8453entry fromaccepts.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-SIGNATUREheader. The service verifies and settles through its facilitator (PayAI) server-side; the settlement receipt comes back in thepayment-responseheader.
Tests
pip install -e ".[dev]"
pytestAll payments mocked (httpx MockTransport, throwaway signer generated
at test time). The 402 fixtures are the real challenges captured from
production; the paid-flow tests verify the EIP-712 signatures actually
recover to the signer address, for both routes.
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 per-route spend guards cap any single call at the configured amounts (defaults: exactly the $0.10 grade and $0.50 fix prices).
Run this with a dedicated agent wallet holding only working funds, the same way you would fund any agent.
Available Tools
2 toolslist_fixA
Repair one x402 route's Bazaar discovery metadata.
Calls ListSmith POST /v1/fix ($0.50 USDC on Base via x402).
Returns a complete repaired discovery package — a full output
schema inferred from your sample, a sub-500-char description with
a use-when sentence, OpenAPI and well-known snippets, and paste-in
instructions. The package ships only if it passes both x402 SDK
validators.
Args:
resource_url: Full URL of the x402 resource to repair.
sample_output: One real response body from the endpoint
(required). The repaired output schema is inferred from
this sample only — nothing is invented.
name: Optional display name for the generated description;
derived from the URL when omitted.
category: Optional category (e.g. token-risk, search, data,
media, monitoring) used to phrase the description's
use-when sentence.
Inputs: resource_url (required), sample_output (required), name, category. Returns: object
list_gradeA
Grade one x402 route's Bazaar discovery metadata.
Calls ListSmith POST /v1/grade ($0.10 USDC on Base via x402).
Returns SDK validation verdicts, a schema-quality score, itemized
defects with severities, and a 0-100 grade. Diagnosis only — no
repaired content. Use list_fix when you want the repair.
Args:
resource_url: Full URL of the x402 resource to grade.
sample_output: Optional real response body from the endpoint;
when supplied, it is also checked against the endpoint's
published output schema.
Inputs: resource_url (required), sample_output. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
list_grade (diagnosis) and list_fix (repair) target clearly different outcomes and the descriptions explicitly cross-reference each other ('Use list_fix when you want the repair'), so misselection is unlikely. The only friction is semantic: an agent could briefly read 'list_grade' as 'enumerate grades' before the description corrects it.
Both tools use the same snake_case list_<verb> pattern, so the set is internally consistent. The chosen verb ('list') is semantically wrong for both operations (grade / fix), which is a minor deviation from the ideal verb_noun accuracy, but it is applied uniformly.
Two tools is thin for a server with a paid two-step workflow; there is no ungraded/ungraded-batch entry point or overview tool. It is a defensible minimal surface (diagnose, then repair), but it sits at the borderline of the '1-2 tools feels thin' band.
The grade -> fix loop covers the full lifecycle for a single x402 route: detection, itemized defects, and a validated repair package, with no dead end. Gaps are minor and workaroundable: no batch grading across multiple routes, no way to re-fetch a previously generated repair, and sample_output is required for fix but optional for grade.
Related MCP Connectors
Pay-per-call AI micro-tasks for agents. 20 tasks - summarize, code review, JSON, media - from $0.003 USDC on Base. x402 v2. Free discovery tools: list_tasks, price_task, check_health.
Validates JSON against a JSON Schema, lists violations. x402 payment required (Base mainnet USDC).
Paid tools for AI agents via x402 (USDC on Base): text rewrite, writing grade, code lookups.
26 pay-per-call AI agent tools for marketing, sales, content, research, verification, and integration testing. Agents pay per call via x402 micropayments (USDC on Base), raw JSON in and out. Includes delivery-acceptance receipts (ACCEPT/REJECT/REVIEW), a webhook capture/replay/conformance lab, and n8n workflow validation with bounded JSON-Patch repair.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceDiscovers and queries x402-payable APIs at runtime — enables autonomous agents to find, evaluate, and pay for services via USDC micropayments on Base without API keys or subscriptions.MIT
- AlicenseNot gradedqualityCmaintenanceEnables agents to access production-grade paid MCP tools with real on-chain x402 v2 settlement, including EVM wallet risk scoring, payload normalization, and facilitator discovery, all discoverable via Bazaar-compatible metadata.MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI agents to discover and invoke x402-monetized computational engines for media geometry, measurements, JSON hygiene, and ComfyUI preflight audits, with USDC settlement on Base Mainnet.-
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to discover, pay for, and invoke x402-priced services such as document OCR, document analysis, media transcription, remote browser sessions, and receive-only email inboxes using USDC on Base, with no API keys and receipt-backed results.38MIT