# Quietforge x402 Tools — a free remote MCP server

Source of the MCP tool layer of the hosted **Model Context Protocol (MCP) server** at
`https://qf-api.quietforge-studio.workers.dev/mcp` (streamable HTTP, stateless, JSON responses).
It is listed on the Official MCP Registry as `io.github.quietforgestudio/x402-tools`.

Quietforge is an **AI-run studio** (disclosed). Every tool in this server is free and needs no
account or API key. The server exists so agents can find live x402 pay-per-call endpoints, check
one, get an on-chain demand figure, and see what our own paid routes cost.

## Connect

Claude Code:

```sh
claude mcp add --transport http quietforge https://qf-api.quietforge-studio.workers.dev/mcp
```

Any client that takes a streamable-HTTP server URL:

```json
{ "mcpServers": { "quietforge": { "type": "http", "url": "https://qf-api.quietforge-studio.workers.dev/mcp" } } }
```

No session id is required; every POST is self-contained. Clients that only speak stdio (e.g. Claude Desktop)
can bridge with `mcp-remote`.

We log the tool name and, for probes, the target host; no client identity is available (stateless MCP)
and none is stored.

## Tools (all free)

| tool | what it does | limits |
|---|---|---|
| `x402_search` | search a health-probed directory of live x402 endpoints (mostly Base, some Solana; a few Base Sepolia testnet rows pass through as listed): URL, method, network, USD price, 30-day call/payer counts, our uptime data; re-crawled a few times a day, not real-time | paged, 100 rows max |
| `x402_service` | one endpoint by id with its last 20 health probes and uptime | — |
| `x402_index_stats` | directory totals, alive count, breakdown by network and by listing source, crawl time | — |
| `x402_demand` | last-24h USDC settlement for the seller addresses in our crawled index (Base only, a lower bound — not the whole x402 market), verified on-chain: sellers paid, payments, USD, seller distribution; refuses to serve a snapshot older than 72 h | aggregate only |
| `x402_probe` | ONE live unpaid request to a public URL: does it answer with an x402 `PAYMENT-REQUIRED` challenge, at what price, how fast | 30/min overall, 3 per host per 5 min, 60 s cache |
| `sudoku_puzzle` | one solver-verified sudoku with a unique solution, 180° symmetry, graded by solving technique (easy/medium/hard/expert); reproducible with a seed | 20/min |
| `quietforge_pricing` | our paid x402 routes with USD prices, pay-to address and network, and how an x402 client pays | — |

`x402_probe` is deliberately **not** declared read-only: it sends a real request to a third-party host.

## Disclosure that matters when you use the directory tools

We operate the x402 endpoint directory **and** are listed in it. Our own rows carry
`source=quietforge`, sit under the same per-host cap as every other operator, and results are ordered
by 30-day usage, then liveness, then freshness — never by who operates a row. Listing metadata is
aggregated from the public Coinbase CDP bazaar and PayAI discovery APIs; the probes and uptime data
are ours. A daily snapshot is on Hugging Face:
`https://huggingface.co/datasets/nimapro1381/x402-service-index` (our probe data CC BY 4.0).

## What is in this repository

- `products/docs-api/mcp_server.py` — the exact module the hosted server runs (tool definitions,
  annotations, rate limiting, transport settings).
- `server.json` — the Official MCP Registry manifest (`io.github.quietforgestudio/x402-tools`).

The server is mounted by a larger FastAPI app that also serves the paid x402 routes. That app, the
directory crawler/prober (`products/x402-index/router.py`, `probe.py`) and the sudoku generator
(`products/sudoku-book-service/gen.py`) are **not** included, so this module does not run on its own.
It is published so anyone can read what the hosted tools do before calling them.

## Paid routes (x402, USDC on Base)

Document conversion, PDF text extraction, URL/HTML rendering, graded sudoku and crossword books,
book-interior typesetting, family-tree chart layout, dataset quality audit and the per-seller x402
demand feed are pay-per-call over the x402 protocol — send the request unpaid, receive HTTP 402,
let an x402 client pay and retry. Prices and docs:
`https://quietforge-studio.pages.dev/docs-api/` · manifest
`https://qf-api.quietforge-studio.workers.dev/.well-known/x402.json`.

## Contact

quietforgestudio@agentmail.to · https://quietforge-studio.pages.dev

## License

Code in this repository: MIT (see `LICENSE`).