Skip to main content
Glama
QuincyGB

ListSmith MCP

by QuincyGB
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

list-smith-mcp

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 (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

resource_url

string (required)

Full URL of the x402 resource to grade

sample_output

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

resource_url

string (required)

Full URL of the x402 resource to repair

sample_output

any (required)

One real response body from the endpoint. The repaired output schema is inferred from this sample only — nothing is invented

name

string (optional)

Display name for the generated description; derived from the URL when omitted

category

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: agent-toolkit-mcp

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

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.

LIST_SMITH_URL

no

Service base URL override (default: production).

LIST_SMITH_GRADE_MAX_AMOUNT_UNITS

no

Spend guard for /v1/grade in USDC micro-units (default 100000 = $0.10, the known price).

LIST_SMITH_FIX_MAX_AMOUNT_UNITS

no

Spend guard for /v1/fix in USDC micro-units (default 500000 = $0.50, the known price).

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):

  1. POST /v1/grade or /v1/fix 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

All 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 tools
list_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.
NameRequiredDescriptionDefault
nameNo
categoryNo
resource_urlYes
sample_outputYes

Output Schema

NameRequiredDescription

No output parameters

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so: it discloses the $0.50 USDC cost on Base via x402 payment, that the package is gated on passing both x402 SDK validators, and that the output schema is inferred from the sample only with nothing invented. These are exactly the non-obvious traits an agent needs before invoking a paid mutation-style tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then cost/endpoint, then the return contract, then args — good ordering with no filler. The Args block is somewhat verbose for a tool whose parameter names already self-document, but the extra semantics justify most of it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers cost, payment rail, required inputs, output package contents, and the validation gate; an output schema exists so return-value detail needn't be restated. Nothing an agent needs to invoke this correctly appears missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it documents all four parameters: resource_url as the target, sample_output as required and the sole source of schema inference, name as optional and derived from the URL when omitted, and category with concrete example values. This is materially more than the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Repair one x402 route's Bazaar discovery metadata,' and pins the underlying call to ListSmith POST /v1/fix. An agent can tell this is the remediation action, distinct from the sibling list_grade evaluation tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies the use case clearly (repairing broken/missing discovery metadata) and specifies the required input discipline (one real sample response). It never explicitly says when not to use it or points to list_grade as the alternative, so it stops short of full routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.
NameRequiredDescriptionDefault
resource_urlYes
sample_outputNo

Output Schema

NameRequiredDescription

No output parameters

TDQS

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so: it discloses the underlying endpoint (POST /v1/grade), a concrete paid-call cost ($0.10 USDC on Base via x402), and the shape of the verdict returned. The paid-invocation requirement is critical context an agent would otherwise not know before calling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action, then cost, then return shape, then the sibling routing, then params. The Args block is not wasted redundancy here because the schema is empty, so it is the only source of parameter documentation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the action, the payment cost, the returned verdicts/score/defects/grade, the diagnosis-only constraint, and the repair alternative. An output schema exists, yet the description still summarizes the return shape usefully; nothing needed to invoke correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% — sample_output has no type or description at all — so the description must compensate, and it does: resource_url is defined as a full URL, and sample_output is explained both as an optional real response body and as the trigger for the extra output-schema check.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — grade one x402 route's Bazaar discovery metadata — and immediately names the sibling list_fix as the repair counterpart, so an agent can distinguish the two without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly frames the tool as diagnosis only with no repaired content, then routes the agent: 'Use list_fix when you want the repair.' The selection condition between the two siblings is fully stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 2 tool updatesv0.1.1
    • First observedlist_fix
    • First observedlist_grade
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A4.5/5.0

Scored across 2 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count3/5

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.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • x402-discovery

    rplryan
    A
    license
    Not graded
    quality
    D
    maintenance
    Discovers 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

  • agent-toolkit-mcp

    white-hat-lab
    F
    license
    Not graded
    quality
    B
    maintenance
    Provides coding agents with 19 pay-per-call developer utilities, npm supply-chain security checks, and Base blockchain lookups, paid via USDC on Base using x402. No API key needed—payment acts as authentication.
    42 npm
    -

  • a2a-x402-mcp-services

    Disseveru
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables 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