gold402-mcp

<!-- mcp-name: io.github.Haustorium12/gold402-mcp -->

An MCP server over gold-402 — the curated x402 directory maintained by 24K Labs. Gives any MCP-capable agent (Claude, Cursor, or anything speaking MCP) four tools for finding x402 services and for checking an endpoint before it spends money against it.

Status: v0.1 — tested, packaged, not yet published. Runs over stdio.

Tools

Tool	What it does
gold402_search	Search the shelf by free text and/or shelf name. Paginated. Every answer states how many entries it actually searched.
gold402_list_sections	All 13 shelves with their true curated counts, and how many of each are searchable here.
gold402_get_entry	One entry by name — URL, description, shelf, date first listed, permanent listing page.
gold402_check_endpoint	Live-probe any x402 endpoint, listed or not. One unpaid request: does it answer, is it a real 402, what are the payment terms, does the origin publish a manifest — plus whether it's on our shelf.
gold402_verdict	Paid, $0.001 USDC on Base. The 24K Labs editorial verdict for one resource plus aggregated independent rater grades. The judgement layer — a maintainer looked at it and put a name behind it.

Free vs paid

Four of the five tools are free and stay free — search, shelves, entry lookup, and the live probe. No key, no wallet, no account.

gold402_verdict is paid: $0.001 USDC on Base. It is the only one, and it buys the thing the free probe explicitly does not give you — a human judgement. A valid 402 proves the door works; the verdict is a maintainer saying it was worth a stranger's money.

This server never holds a wallet and never pays on your behalf. Call gold402_verdict once with no payment_signature and it hands back the decoded x402 terms — price, network, asset, payTo, timeout. Sign them with your own wallet and call again with the signature. The money goes from you to 24K Labs; this process is not in the path.

gold402_check_endpoint is the door check the maintainers run, made callable. It works on endpoints that are not in the directory, which is the point: an agent about to pay a stranger can ask first.

What the answers claim, and what they don't

Listing means a maintainer probed it and it answered an x402 request correctly at the time of review, and we re-probe periodically. It is not an audit of the provider, a guarantee of uptime, or a promise that any call will succeed. A valid 402 proves the door works — not that the service delivers. Every response carries an as_of stamp and the upstream it came from.

Absence from the directory is not a verdict against a service. It's a curated list, not a census.

Install

uvx gold402-mcp            # no install step
pip install gold402-mcp    # then run: gold402-mcp

From a clone:

python3 -m venv .venv && ./.venv/bin/pip install -e .
./.venv/bin/gold402-mcp

Client config

Claude Desktop / Claude Code (claude_desktop_config.json or .mcp.json):

{
  "mcpServers": {
    "gold402": {
      "command": "uvx",
      "args": ["gold402-mcp"]
    }
  }
}

Prefer pip? Install it, then use "command": "gold402-mcp" with no args.

Data source

https://24klabs.ai/directory.json — public, published, cached 15 minutes. No key, no auth, no scraping. If the fetch fails and a cached copy exists, the cached copy is served and its age is disclosed rather than hidden.

Coverage, stated plainly. That endpoint is a deliberate preview: it carries the full shelf structure and true per-shelf counts, but only the most recently listed entries as records. 24K Labs does not serve the full set in bulk to anonymous callers (why). So this server does not imply reach it does not have:

• every response reports both the curated total and how many entries were actually searched;
• a shelf with no preview records is reported as a coverage limit, never as an empty or nonexistent shelf;
• for anything outside the preview: browse https://24klabs.ai/directory, look up one resource at /api/v1/verify?resource=<url>, or use gold402_check_endpoint, which works on any endpoint whether or not it is listed.

Tests

./.venv/bin/python test_tools.py    # tool-level, incl. error paths
./.venv/bin/python test_stdio.py    # end-to-end over the real MCP protocol

Both pass as of 2026-08-20, including against the installed console script (clean venv, pip install from the built wheel) — not just the source file.

---

Curated by 24K Labs · directory: https://github.com/Haustorium12/gold-402