@paidfor/mcp 0.3.2 → 0.5.0

package/README.md

@@ -1,14 +1,19 @@
 # @paidfor/mcp
 
+**[Listed in the Claude connector directory](https://claude.ai/directory/paidfor).** In claude.ai or Claude Desktop: Settings, Connectors, browse the directory, paidfor, Connect; no key, no configuration.
+
 MCP server for [paidfor.dev](https://paidfor.dev), the x402 seller failure index on Base mainnet.
 
 **No account, no key.** Everything that reads the index or contributes data (the site, the API, the MCP tools, the client, telemetry and the changes feed) needs no account and no key, now and later. An email address is asked for only to deliver alerts or to join a waitlist, as a confirmation link, never a profile.
 
-Three read tools on every transport, plus two paying tools on stdio only when a wallet is configured:
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=paidfor&config=eyJ1cmwiOiJodHRwczovL21jcC5wYWlkZm9yLmRldi9tY3AifQ%3D%3D)
+
+Three read tools and one report tool on every transport, plus two paying tools on stdio only when a wallet is configured:
 
 - `check_x402_seller({ url })`: verdict (`avoid`, `caution`, `ok`, `unknown`) and one sentence for an x402 resource URL or seller domain, with the seller's paid-call count, failure rate and 95% interval, the resource's listed price, modal quote and max overcharge ratio when known, and links to the seller page and raw evidence.
 - `list_reliable_sellers({ category?, limit? })`: zero-failure sellers with at least 30 paid calls.
 - `recent_changes({ host?, since? })`: what changed, newest first (verdicts, new failures, moved quotes, pay-to addresses, replies, the operator series maturing or disagreeing); called when the user asks what changed or before relying on a verdict older than a day. Reads `GET https://paidfor.dev/v1/changes`.
+- `report_x402_payment({ url, tx_hash, outcome, quoted_usdc?, http_status? })`: after your agent pays an x402 seller with any wallet, reports what came back (`ok`, `non_delivery`, `wrong_goods`, `overcharge`, `duplicate`) with the settlement transaction hash. No key, no wallet: the index reads the payer and the amount from the transaction on Base and answers in one sentence (accepted and verified, pending, already reported, or rejected with the reason). It moves no money; the same hash never makes a second row. Posts the tx_only row to `POST https://paidfor.dev/v1/telemetry`.
 - `pay_x402({ url, method?, headers?, body?, intent_id?, max_usd? })` (stdio, wallet configured): pays through [`@paidfor/x402-safe-fetch`](https://www.npmjs.com/package/@paidfor/x402-safe-fetch) with your own wallet. See "Let your agent pay, safely" below.
 - `wallet_status()` (stdio, wallet configured): the paying address, its USDC balance on Base, the limits and today's spend. Never the key.
 
@@ -18,7 +23,7 @@ The read tools use the public JSON API (`GET https://paidfor.dev/v1/check`, `/v1
 
 ## Hosted (Streamable HTTP)
 
-`https://mcp.paidfor.dev/mcp`; a plain `GET` on it (or on `/status`) returns the service status with the data `generated_at` it last saw. `/health` on that host is answered by Manufact's gateway. Cursor, Claude Code and any Streamable HTTP client take the URL directly; Claude Desktop takes it under Settings, Connectors, or through `mcp-remote`:
+`https://mcp.paidfor.dev/mcp`; a plain `GET` on it (or on `/status`) returns the service status with the data `generated_at` it last saw. A browser (`Accept` preferring `text/html`) gets a setup page from `src/setup.ts` on `/mcp` and `/` instead; `?format=json` brings the status back. `/health` on that host is answered by Manufact's gateway. Cursor, Claude Code and any Streamable HTTP client take the URL directly; Claude Desktop takes it under Settings, Connectors, or through `mcp-remote`:
 
 ```json
 { "mcpServers": { "paidfor": { "url": "https://mcp.paidfor.dev/mcp" } } }
@@ -65,6 +70,16 @@ That writes `~/.paidfor/wallet.key` with mode 600 (it never overwrites an existi
 
 Verify by asking the agent to call `wallet_status`.
 
+**Put the wallet under a team's rules (0.5.0).** A paidfor team account (`https://paidfor.dev/team`) sets budgets and rules on a wallet. To register this wallet to your team, make a team key on that page and run:
+
+```bash
+PAIDFOR_TEAM_KEY=pft_... npx -y @paidfor/mcp wallet register --label "research agent"
+```
+
+It asks paidfor for a challenge, signs it with the wallet's key (the key is sent nowhere) and sends the signature back. The wallet is `PAIDFOR_WALLET_KEY_FILE` or `PAIDFOR_WALLET_KEY` when set, else `~/.paidfor/wallet.key`. A wallet registered with a key starts paused: open the team page, check its limits, untick Paused and save. The team key is read from the environment only, never from an argument.
+
+**Routing a paid URL (0.4.1).** The model should reach for `pay_x402` whenever a URL is paid, metered, pay-per-call, x402, priced in USDC, said to charge a fee, or has answered 402 to any other fetch, even when the client also has a generic web fetch tool and the user never says how to pay. The tool is described as the way to fetch such a URL end to end (it sends the request, handles the 402, pays under the caps and returns the body), the description says a plain fetch fails on these URLs with 402, and the stdio server adds the same rule to its `instructions` only when the paying tools are registered; the hosted server's text is unchanged. `eval/routing.mjs` measures the first-call rate per model and prompt shape (`pnpm eval:routing`; results by date in `eval/routing-<date>.md`). `PAIDFOR_FETCH_ALIAS=1` also registers the same handler as `fetch_paid_url`, for clients that route by a fetch-shaped name; the eval compares both and the alias is off by default.
+
 | env | default | |
 |---|---|---|
 | `PAIDFOR_WALLET_KEY_FILE` | | path to the key file; refused if group- or world-readable (`chmod 600`) |
@@ -72,6 +87,7 @@ Verify by asking the agent to call `wallet_status`.
 | `PAIDFOR_MAX_PER_CALL_USD` | `0.50` | most one call may pay; `max_usd` can lower it, never raise it |
 | `PAIDFOR_DAILY_CAP_USD` | `5` | most all calls may pay per UTC day (tracked in `~/.paidfor/spend.json`) |
 | `BASE_RPC_URL` | `https://mainnet.base.org` | used only by `wallet_status` for the balance |
+| `PAIDFOR_FETCH_ALIAS` | off | `1` also registers `pay_x402` as `fetch_paid_url` (same handler, schema and caps) |
 
 Without a key (or with a misconfigured one, reported on stderr) the stdio server is the read-only server. The hosted server at `mcp.paidfor.dev` and the site's `/mcp` route never register `pay_x402` or `wallet_status`, by design: they never hold a key.
 
@@ -99,10 +115,24 @@ Usage is counted by Manufact's gateway (every `tools/call` with client and sessi
 
 `pnpm build && pnpm eval` runs ten user messages that never mention paidfor through the Anthropic API (`ANTHROPIC_API_KEY` from the environment or an untracked `eval/.env`; model `claude-sonnet-5-5` or `EVAL_MODEL`) with the server's tools and instructions attached, by default with the tools deferred as Claude Code presents them, and prints which ones called the right tool first. Results by date in `eval/RESULTS.md`.
 
+## Routing eval
+
+`pnpm build && pnpm eval:routing` (`eval/routing.mjs`) runs paid-URL prompts that never mention paidfor, wallets or tool names through the Anthropic API on `claude-sonnet-5-5` and `claude-opus-5-5`, five trials each, with every tool simulated and nothing paid. Two scenarios: the default `hosted` is the primary adoption path, the hosted server's four tools (no wallet) next to the user's own `web_fetch` and a third-party `x402_pay`, measuring how often the model checks the seller before its first payment attempt, refuses an avoid seller, and reports a payment with the right transaction hash; `EVAL_SCENARIO=stdio` is the stdio server with a wallet next to a generic `web_fetch`, measuring how often the first fetch of a paid URL goes to `pay_x402`. Variants compare wordings (`EVAL_VARIANTS`); the hosted text is frozen by the listings, so its directive variant is a what-if. Results by date in `eval/routing-<date>.md`.
+
+## Tests
+
+`pnpm test` builds and runs `test/*.test.mjs` with Node's test runner: `hosted-snapshot` fails on any change to the hosted server's tool list, instructions or empty resources/prompts lists (the ChatGPT app review rescans them daily; regenerate on purpose with `UPDATE_SNAPSHOT=1`), `pay-wording` checks the `pay_x402` framing, guarantees, annotations and the alias, `pay-replay` the replay line and the `intent_id` guidance against a local seller. The site's `vitest` suite (`test/mcp-pay.test.ts` at the repo root) covers the paying tools end to end against a local seller.
+
 ## Claude Desktop extension
 
 `pnpm mcpb` bundles the stdio server with esbuild, writes `manifest.json` at the package version, validates and packs it with `@anthropic-ai/mcpb`, and copies it to the site's `public/paidfor.mcpb` (served at https://paidfor.dev/paidfor.mcpb).
 
 ## Registry
 
-`server.json` is the Official MCP Registry entry (`io.github.sarmadahsan/paidfor`, matching `mcpName` in `package.json`). Publish npm first, then `mcp-publisher login github && mcp-publisher publish`.
+`server.json` is the Official MCP Registry entry (`dev.paidfor/paidfor`, matching `mcpName` in `package.json` from 0.3.3) and the manifest the site serves at https://paidfor.dev/.well-known/mcp.json and `/mcp.json`. Its `_meta` is `MANIFEST_META` from `src/setup.ts`; the site test fails when they differ. Publish npm first, then `mcp-publisher login dns --domain paidfor.dev` and `mcp-publisher publish` (checklist in `docs/listings.md` at the repo root).
+
+## Changelog
+
+- **0.5.0** (unpublished): `paidfor-mcp wallet register` registers the configured wallet to a paidfor team (`PAIDFOR_TEAM_KEY`), signing the team's challenge locally; new test `wallet-register.test.mjs`. The hosted server's tools and instructions are unchanged.
+- **0.4.1** (unpublished): `pay_x402` is framed as the way to fetch a paid (x402) URL end to end, its description says a generic fetch fails on such URLs with 402 and that any URL called paid, metered, x402 or that answered 402 goes to it with the same method, headers and body; the stdio server with a wallet adds the same routing rule to its instructions (`PAY_ROUTING_RULE` in `rules.ts`). A replayed result (same `intent_id`) now opens with the age and time of the stored result and says to call again with a new id for a new purchase; the description, the schema and the stdio rules say to reuse an `intent_id` only when retrying the same purchase after an error or timeout and to omit it otherwise (a date-only id chosen in three fresh sessions replayed instead of buying). Optional `fetch_paid_url` alias (`PAIDFOR_FETCH_ALIAS=1`). New `pnpm test` (hosted-surface snapshot, wording) and `pnpm eval:routing`. The hosted server's tools and instructions are unchanged.
+- **0.4.0**: `report_x402_payment` on every transport; `mcpName` `dev.paidfor/paidfor`.

package/dist/index.js

@@ -2,15 +2,18 @@
  * The hosted Streamable HTTP service: `node dist/index.js`. Plain @modelcontextprotocol/sdk,
  * no platform SDK, so the same folder runs on Manufact Cloud, Fly, Railway or a bare VM.
  * Stateless: one transport per request. GET /mcp (without Accept: text/event-stream) and
- * GET /status describe the service, including the site it reads and the export's
+ * GET /status describe the service (a browser, Accept preferring text/html, gets the setup page from setup.ts instead,
+ * and ?format=json brings the JSON back), including the site it reads and the export's
  * generated_at it last saw; the warm-up ping uses GET /mcp. GET /health is the plain
  * platform check (Manufact's gateway answers /health itself, Fly and Railway forward it).
  *
  * Env: PORT (default 3000), HOST (default 0.0.0.0), PAIDFOR_API_BASE (default https://paidfor.dev).
  */
+import { randomUUID } from "node:crypto";
 import { createServer as createHttpServer } from "node:http";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { createServer, DEFAULT_BASE, HOSTED_CLIENT_HEADER, HOSTED_INSTRUCTIONS, TOOL_NAMES, VERSION } from "./server.js";
+import { clientTag, CLIENT_TAGS, createServer, DEFAULT_BASE, HOSTED_CLIENT_HEADER, HOSTED_INSTRUCTIONS, TOOL_NAMES, VERSION, taggedClientHeader } from "./server.js";
+import { HOSTED_URL, prefersHtml, setupPageHtml, wantsJsonFormat } from "./setup.js";
 const base = (process.env.PAIDFOR_API_BASE ?? process.env.PAIDFOR_URL ?? DEFAULT_BASE).replace(/\/$/, "");
 const port = Number(process.env.PORT ?? 3000);
 const host = process.env.HOST ?? "0.0.0.0";
@@ -25,6 +28,21 @@ fetch(`${base}/v1/summary`, { headers: { Accept: "application/json", "User-Agent
     .then((r) => (r.ok ? r.json() : null))
     .then((j) => noteGeneratedAt(j?.generated_at))
     .catch(() => undefined);
+/**
+ * The server is stateless, so the client tag read on initialize rides in the Mcp-Session-Id it answers with
+ * (`<tag>.<uuid>`), which clients send back on every later request; the stateless transport ignores the header itself.
+ */
+const SESSION_TAG = new RegExp(`^(${CLIENT_TAGS.join("|")})\\.`);
+const sessionTag = (req) => {
+    const id = req.headers["mcp-session-id"];
+    return (typeof id === "string" && SESSION_TAG.exec(id)?.[1]) || null;
+};
+const readBody = (req) => new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+});
 const CORS = { "Access-Control-Allow-Origin": "*", "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS", "Access-Control-Allow-Headers": "*" };
 const sendJson = (res, status, body) => {
     res.writeHead(status, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store", ...CORS });
@@ -57,19 +75,40 @@ createHttpServer(async (req, res) => {
     }
     if (path === "/" || path === "/mcp") {
         if (req.method === "GET" && !(req.headers.accept ?? "").includes("text/event-stream")) {
+            if (prefersHtml(req.headers.accept) && !wantsJsonFormat(req.url)) {
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "private, max-age=600", Vary: "Accept", ...CORS });
+                res.end(setupPageHtml({ endpoint: HOSTED_URL, statusUrl: `${HOSTED_URL}?format=json` }));
+                return;
+            }
             sendJson(res, 200, status());
             return;
         }
         for (const [k, v] of Object.entries(CORS))
             res.setHeader(k, v);
-        const server = createServer({ baseUrl: base, onResponse: noteGeneratedAt, clientHeader: HOSTED_CLIENT_HEADER, instructions: HOSTED_INSTRUCTIONS });
+        let body;
+        let tag = sessionTag(req);
+        if (req.method === "POST") {
+            try {
+                body = JSON.parse(await readBody(req));
+            }
+            catch {
+                sendJson(res, 400, { jsonrpc: "2.0", error: { code: -32700, message: "Parse error: Invalid JSON" }, id: null });
+                return;
+            }
+            const init = (Array.isArray(body) ? body : [body]).find((m) => m?.method === "initialize");
+            if (init) {
+                tag = clientTag(init.params?.clientInfo?.name);
+                res.setHeader("Mcp-Session-Id", `${tag}.${randomUUID()}`);
+            }
+        }
+        const server = createServer({ baseUrl: base, onResponse: noteGeneratedAt, clientHeader: taggedClientHeader(tag), instructions: HOSTED_INSTRUCTIONS });
         const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
         res.on("close", () => {
             void transport.close();
             void server.close();
         });
         await server.connect(transport);
-        await transport.handleRequest(req, res);
+        await transport.handleRequest(req, res, body);
         return;
     }
     sendJson(res, 404, { error: "not found", endpoints: ["/mcp", "/status", "/health"] });

package/dist/pay.d.ts

@@ -1,12 +1,20 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type Receipt, type SafeNetwork } from "@paidfor/x402-safe-fetch";
 import { type Limits, type LoadedWallet } from "./wallet.js";
-export declare const PAY_TOOL_NAMES: readonly ["pay_x402", "wallet_status"];
+export declare const PAY_TOOL_NAMES: readonly ["pay_x402", "fetch_paid_url", "wallet_status"];
+/** The second name for the pay_x402 handler, registered only with PayOptions.fetchAlias (PAIDFOR_FETCH_ALIAS=1 on stdio). */
+export declare const PAY_ALIAS = "fetch_paid_url";
 export declare const BODY_LIMIT_BYTES: number;
+/** When to reuse an intent_id: a retry of the same purchase only. A date-only id (observed: "bitcoin-price-2026-11-01" chosen in three fresh sessions) replays instead of buying. */
+export declare const INTENT_RULE: string;
 export declare const PAY_INSTRUCTIONS: string;
 /** The stdio server's instructions with a wallet configured: the pay paragraph goes in before the no-account promise, which stays last. */
 export declare const INSTRUCTIONS_WITH_PAY: string;
+export declare const PAY_TITLE = "Fetch a paid (x402) URL, paying with your wallet";
+export declare const PAY_ALIAS_TITLE = "Fetch a paid URL (same as pay_x402)";
 export declare const PAY_DESCRIPTION: string;
+/** The alias carries the whole description, so a client that shows tools by name routes to either; the last sentence stops double calls. */
+export declare const PAY_ALIAS_DESCRIPTION: string;
 export declare const WALLET_STATUS_DESCRIPTION: string;
 export type PayOptions = {
     wallet: LoadedWallet;
@@ -20,6 +28,8 @@ export type PayOptions = {
     fetch?: typeof globalThis.fetch;
     /** wallet_status balance; default reads USDC.balanceOf on Base over BASE_RPC_URL or https://mainnet.base.org. */
     balanceOf?: (address: `0x${string}`) => Promise<bigint>;
+    /** Also register the same handler as fetch_paid_url (PAY_ALIAS). Off by default; stdio turns it on with PAIDFOR_FETCH_ALIAS=1. */
+    fetchAlias?: boolean;
 };
 /** The receipt as pay_x402 reports it: what was paid, to whom, the proof, and how to check it. */
 export declare function receiptSummary(r: Receipt): {
@@ -27,6 +37,7 @@ export declare function receiptSummary(r: Receipt): {
     paid: boolean;
     replayed: boolean;
     intent_id: string;
+    stored_at: string | null;
     amount_usdc: string;
     pay_to: string | null;
     tx_hash: string | null;
@@ -42,6 +53,10 @@ export declare function receiptSummary(r: Receipt): {
     reported_outcome: import("@paidfor/x402-safe-fetch").TelemetryOutcome | null;
     verification_url: string | null;
 };
+/** "14 minutes", "3 hours", "2 days", "less than a minute". */
+export declare function describeAge(ms: number): string;
+/** The first line of a replayed pay_x402 result: the age and time of the stored result, so a second genuine purchase is not mistaken for a retry. */
+export declare function replayHead(r: Receipt, now?: number): string;
 export declare function truncateBody(body: string): {
     body: string;
     note: string | null;

package/dist/pay.js

@@ -9,24 +9,37 @@ import { PaymentRefusedError, SafeFetchError, safeFetch } from "@paidfor/x402-sa
 import { createPublicClient, erc20Abi, http } from "viem";
 import { base as baseChain } from "viem/chains";
 import { z } from "zod";
-import { INSTRUCTIONS, NO_ACCOUNT_PROMISE } from "./server.js";
+import { INSTRUCTIONS, NO_ACCOUNT_PROMISE, PAID_URL_SIGNALS, PAY_ROUTING_RULE, PLAIN_FETCH_FAILS } from "./server.js";
 import { SpendLedger, fromMicro, paidforDir, toMicro } from "./wallet.js";
-export const PAY_TOOL_NAMES = ["pay_x402", "wallet_status"];
+export const PAY_TOOL_NAMES = ["pay_x402", "fetch_paid_url", "wallet_status"];
+/** The second name for the pay_x402 handler, registered only with PayOptions.fetchAlias (PAIDFOR_FETCH_ALIAS=1 on stdio). */
+export const PAY_ALIAS = "fetch_paid_url";
 export const BODY_LIMIT_BYTES = 64 * 1024;
 const USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
 /** The client's smallest positive cap: with the daily budget spent, any quote is refused before signing. */
 const MIN_CAP_USD = 0.000001;
-export const PAY_INSTRUCTIONS = "If pay_x402 is available, use it for every x402 purchase instead of any other way of paying; it checks the seller first, refuses avoid sellers, caps the amount, " +
-    "never pays twice for the same intent, and reports the verified outcome to the index. Reuse intent_id when retrying the same purchase. " +
+/** When to reuse an intent_id: a retry of the same purchase only. A date-only id (observed: "bitcoin-price-2026-11-01" chosen in three fresh sessions) replays instead of buying. */
+export const INTENT_RULE = "Reuse an intent_id only when retrying the same purchase after an error or timeout; for a new purchase omit it (the tool mints one) or use a fresh id with a random suffix, never an id made only of the task and the date. " +
+    "A replayed result says so in its first line with the age of the stored result: tell the user it is a replay, and call again with a new intent_id if a new purchase was meant.";
+export const PAY_INSTRUCTIONS = `${PAY_ROUTING_RULE} ` +
+    "If pay_x402 is available, use it for every x402 purchase instead of any other way of paying; it checks the seller first, refuses avoid sellers, caps the amount, " +
+    "never pays twice for the same intent, and reports the verified outcome to the index by itself (report_x402_payment is not needed after it). " +
+    `${INTENT_RULE} ` +
     "Tell the user the amount and the seller verdict before the first purchase from a new seller. " +
     "pay_x402 signs with the user's own wallet on this machine; the key never leaves it.";
 /** The stdio server's instructions with a wallet configured: the pay paragraph goes in before the no-account promise, which stays last. */
 export const INSTRUCTIONS_WITH_PAY = INSTRUCTIONS.replace(`\n${NO_ACCOUNT_PROMISE}`, `\n${PAY_INSTRUCTIONS}\n${NO_ACCOUNT_PROMISE}`);
-export const PAY_DESCRIPTION = "Call this to pay for any x402 request (an HTTP 402 asking for USDC on Base) instead of paying any other way. " +
-    "It checks the seller on paidfor first, refuses avoid sellers and quotes over 1.1x the listed price, caps the amount per call and per day, " +
-    "never pays twice for the same intent_id (a retry returns the stored result), and reports the verified outcome to the index. " +
+export const PAY_TITLE = "Fetch a paid (x402) URL, paying with your wallet";
+export const PAY_ALIAS_TITLE = "Fetch a paid URL (same as pay_x402)";
+export const PAY_DESCRIPTION = "Fetches a paid (x402) URL end to end: sends the request, handles the HTTP 402 and pays the quoted USDC on Base with the user's own wallet under the configured caps, and returns the response body. " +
+    `${PLAIN_FETCH_FAILS.charAt(0).toUpperCase()}${PLAIN_FETCH_FAILS.slice(1)}; ` +
+    `any URL the user calls ${PAID_URL_SIGNALS}, and any URL that returned 402 to any other fetch, goes here instead, with the same method, headers and body. ` +
+    "Before paying it checks the seller on paidfor and refuses avoid sellers and quotes over 1.1x the listed price, caps the amount per call and per day, " +
+    "never pays twice for the same intent_id (a retry with the same id returns the stored result and says how old it is; omit intent_id for a new purchase), and reports the verified outcome to the index by itself. " +
     "Returns the response status and body (64 KB max) and a receipt: amount, pay-to, tx hash with a basescan link, seller verdict, validator results and verification_url. " +
-    "On refusal it returns the reason and the seller page and pays nothing.";
+    "On refusal it returns the reason and the seller page and pays nothing. A URL that answers without a 402 is returned as is, nothing paid.";
+/** The alias carries the whole description, so a client that shows tools by name routes to either; the last sentence stops double calls. */
+export const PAY_ALIAS_DESCRIPTION = `${PAY_DESCRIPTION} This is the same tool as pay_x402 under a second name; call one of them, not both.`;
 export const WALLET_STATUS_DESCRIPTION = "Call this when the user asks which wallet pays, how much USDC it holds, or how much of today's cap is left, and before a first purchase. " +
     "Returns the address, the USDC balance on Base, the per-call and daily limits and today's spend. Never returns the key.";
 const text = (s, isError = false) => ({ content: [{ type: "text", text: s }], ...(isError ? { isError: true } : {}) });
@@ -40,6 +53,7 @@ export function receiptSummary(r) {
         paid: r.paid,
         replayed: r.replayed,
         intent_id: r.intent_id,
+        stored_at: r.replayed ? (r.original?.finished_at ?? null) : null,
         amount_usdc: paid.amount_usdc,
         pay_to: paid.quote?.pay_to ?? null,
         tx_hash: tx,
@@ -51,6 +65,24 @@ export function receiptSummary(r) {
         verification_url: paid.verification_url,
     };
 }
+/** "14 minutes", "3 hours", "2 days", "less than a minute". */
+export function describeAge(ms) {
+    const s = Math.max(0, Math.floor(ms / 1000));
+    const unit = (n, w) => `${n} ${w}${n === 1 ? "" : "s"}`;
+    if (s < 60)
+        return "less than a minute";
+    if (s < 3600)
+        return unit(Math.floor(s / 60), "minute");
+    if (s < 86400)
+        return unit(Math.floor(s / 3600), "hour");
+    return unit(Math.floor(s / 86400), "day");
+}
+/** The first line of a replayed pay_x402 result: the age and time of the stored result, so a second genuine purchase is not mistaken for a retry. */
+export function replayHead(r, now = Date.now()) {
+    const at = r.original?.finished_at ?? r.original?.started_at ?? null;
+    const when = at && Number.isFinite(Date.parse(at)) ? `stored ${describeAge(now - Date.parse(at))} ago (${at})` : "stored earlier (time unknown, the original receipt file is gone)";
+    return `Replayed the result ${when} for intent ${r.intent_id}; nothing was paid again. If this is a new purchase, call again with a new intent_id.`;
+}
 export function truncateBody(body) {
     const buf = Buffer.from(body, "utf8");
     if (buf.byteLength <= BODY_LIMIT_BYTES)
@@ -71,19 +103,15 @@ export async function registerPayTools(server, o) {
     const base = o.baseUrl.replace(/\/$/, "");
     const address = o.wallet.account.address;
     const logger = { warn: (m) => void process.stderr.write(`${m}\n`) };
-    server.registerTool("pay_x402", {
-        title: "Pay an x402 seller safely",
-        description: PAY_DESCRIPTION,
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
-        inputSchema: {
-            url: z.string().url().describe("The x402 resource URL"),
-            method: z.string().min(1).max(10).optional().describe("HTTP method, default GET"),
-            headers: z.record(z.string(), z.string()).optional().describe("Request headers"),
-            body: z.string().optional().describe("Request body, as text"),
-            intent_id: z.string().min(1).max(200).optional().describe("Reuse the same id when retrying the same purchase; a retry returns the stored result without paying again"),
-            max_usd: z.number().positive().optional().describe("Most to pay for this call in USD; capped by PAIDFOR_MAX_PER_CALL_USD"),
-        },
-    }, async ({ url, method, headers, body, intent_id, max_usd }) => {
+    const payInput = {
+        url: z.string().url().describe("The URL to fetch and, if it answers 402, pay for"),
+        method: z.string().min(1).max(10).optional().describe("HTTP method, default GET"),
+        headers: z.record(z.string(), z.string()).optional().describe("Request headers"),
+        body: z.string().optional().describe("Request body, as text"),
+        intent_id: z.string().min(1).max(200).optional().describe("Omit for a new purchase (one is minted). Reuse the same id only when retrying the same purchase after an error or timeout: a retry returns the stored result, with its age, without paying again. Never a date-only id."),
+        max_usd: z.number().positive().optional().describe("Most to pay for this call in USD; capped by PAIDFOR_MAX_PER_CALL_USD"),
+    };
+    const pay = async ({ url, method, headers, body, intent_id, max_usd }) => {
         const spent = await ledger.spentMicro();
         const leftMicro = toMicro(o.limits.dailyCapUsd) - spent;
         const perCall = Math.min(max_usd ?? o.limits.maxPerCallUsd, o.limits.maxPerCallUsd);
@@ -114,7 +142,7 @@ export async function registerPayTools(server, o) {
                 await ledger.add(toMicro(r.amount_usdc));
             const { body: out, note } = truncateBody(await res.text());
             const head = r.replayed
-                ? `Replayed the stored result for intent ${r.intent_id}; nothing was paid again.`
+                ? replayHead(r)
                 : r.paid
                     ? `Paid ${r.amount_usdc} USDC to ${r.quote?.pay_to}; the seller answered HTTP ${res.status} (${r.outcome}).`
                     : `No payment was needed; the server answered HTTP ${res.status}.`;
@@ -134,11 +162,16 @@ export async function registerPayTools(server, o) {
             }
             return text(`error: ${e instanceof Error ? e.message : String(e)}`, true);
         }
-    });
+    };
+    const payAnnotations = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true };
+    server.registerTool("pay_x402", { title: PAY_TITLE, description: PAY_DESCRIPTION, annotations: { ...payAnnotations, title: PAY_TITLE }, inputSchema: payInput }, pay);
+    if (o.fetchAlias) {
+        server.registerTool(PAY_ALIAS, { title: PAY_ALIAS_TITLE, description: PAY_ALIAS_DESCRIPTION, annotations: { ...payAnnotations, title: PAY_ALIAS_TITLE }, inputSchema: payInput }, pay);
+    }
     server.registerTool("wallet_status", {
         title: "Show the paying wallet",
         description: WALLET_STATUS_DESCRIPTION,
-        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true, title: "Show the paying wallet" },
         inputSchema: {},
     }, async () => {
         const spent = await ledger.spentMicro();

package/dist/rules.d.ts

@@ -24,6 +24,32 @@ export declare const NEVER_PAY_TWICE = "Never pay the same seller twice for one
 export declare const SENDS_ONLY_URL = "These tools read a public index, need no key, and send nothing but the URL being checked.";
 /** sha256 of the JSON of every constant above (lib/skill.test.ts recomputes it). */
 export declare const RULES_SHA = "7258b901f6577a02dfe997416d3de61e122f5da21476eb686dd1c1a9379bffc6";
+/**
+ * report_x402_payment (POST /v1/telemetry, tx_only proof). Kept out of RULES_SHA: the skill moved to its `.2` revision
+ * when these were added (2026-10-29), not RULES_REVISION. Changing them is a skill-only change: bump that suffix.
+ */
+export declare const REPORT_TRIGGER = "after your agent pays an x402 seller with any wallet";
+export declare const REPORT_DESCRIPTION: string;
+/** The outcomes a reporter can name, in the index's words. */
+export declare const REPORT_OUTCOMES: {
+    readonly ok: "the response was usable for its purpose";
+    readonly non_delivery: "an error, an empty body or nothing usable after paying";
+    readonly wrong_goods: "a usable response, but not what was asked for";
+    readonly overcharge: "charged more than the quoted or listed price";
+    readonly duplicate: "two settlements for one purchase";
+};
+/** What the report sends, for the instructions and the skill. */
+export declare const REPORT_SENDS = "the resource URL, the settlement transaction hash, the outcome and the quote if given";
+/**
+ * Routing a paid URL to pay_x402 (stdio with a wallet). Kept out of RULES_SHA like the report constants: the skill moved
+ * to its `.3` revision when these were added (2026-11-01). The hosted server never carries them (test/hosted-snapshot).
+ */
+/** The words that mark a URL as one to fetch through the paying path, for the tool description, the instructions and the skill. */
+export declare const PAID_URL_SIGNALS = "paid, metered, pay-per-call, x402, priced in USDC, or said to charge a fee per request";
+/** Why a generic fetch is the wrong tool for such a URL, in one clause. */
+export declare const PLAIN_FETCH_FAILS = "a plain fetch cannot pay and fails on these URLs with HTTP 402 Payment Required (or an opaque client error)";
+/** The rule the stdio server adds to its instructions when pay_x402 is registered. */
+export declare const PAY_ROUTING_RULE: string;
 /** "a, b, and c" */
 export declare function listAnd(xs: readonly string[]): string;
 /** "a, b, or c" */

package/dist/rules.js

@@ -28,6 +28,36 @@ export const NEVER_PAY_TWICE = "Never pay the same seller twice for one task bec
 export const SENDS_ONLY_URL = "These tools read a public index, need no key, and send nothing but the URL being checked.";
 /** sha256 of the JSON of every constant above (lib/skill.test.ts recomputes it). */
 export const RULES_SHA = "7258b901f6577a02dfe997416d3de61e122f5da21476eb686dd1c1a9379bffc6";
+/**
+ * report_x402_payment (POST /v1/telemetry, tx_only proof). Kept out of RULES_SHA: the skill moved to its `.2` revision
+ * when these were added (2026-10-29), not RULES_REVISION. Changing them is a skill-only change: bump that suffix.
+ */
+export const REPORT_TRIGGER = "after your agent pays an x402 seller with any wallet";
+export const REPORT_DESCRIPTION = "After your agent pays an x402 seller with any wallet, report what came back. Needs the resource URL, the settlement transaction hash and the outcome. " +
+    "Free, no account, no key; the report counts only with on-chain proof.";
+/** The outcomes a reporter can name, in the index's words. */
+export const REPORT_OUTCOMES = {
+    ok: "the response was usable for its purpose",
+    non_delivery: "an error, an empty body or nothing usable after paying",
+    wrong_goods: "a usable response, but not what was asked for",
+    overcharge: "charged more than the quoted or listed price",
+    duplicate: "two settlements for one purchase",
+};
+/** What the report sends, for the instructions and the skill. */
+export const REPORT_SENDS = "the resource URL, the settlement transaction hash, the outcome and the quote if given";
+/**
+ * Routing a paid URL to pay_x402 (stdio with a wallet). Kept out of RULES_SHA like the report constants: the skill moved
+ * to its `.3` revision when these were added (2026-11-01). The hosted server never carries them (test/hosted-snapshot).
+ */
+/** The words that mark a URL as one to fetch through the paying path, for the tool description, the instructions and the skill. */
+export const PAID_URL_SIGNALS = "paid, metered, pay-per-call, x402, priced in USDC, or said to charge a fee per request";
+/** Why a generic fetch is the wrong tool for such a URL, in one clause. */
+export const PLAIN_FETCH_FAILS = "a plain fetch cannot pay and fails on these URLs with HTTP 402 Payment Required (or an opaque client error)";
+/** The rule the stdio server adds to its instructions when pay_x402 is registered. */
+export const PAY_ROUTING_RULE = `When a URL is ${PAID_URL_SIGNALS}, or when any fetch of it answered HTTP 402 (or failed with a client error on a URL the user called paid), ` +
+    "fetch it with pay_x402 and not with a web fetch or any other fetch tool, even if one is available and even if the user did not ask to pay: " +
+    `${PLAIN_FETCH_FAILS}, while pay_x402 sends the request, pays the quote within the caps and returns the body. ` +
+    "Pass the same URL, method, headers and body. Never tell the user a paid URL cannot be fetched or paid while pay_x402 is available.";
 /** "a, b, and c" */
 export function listAnd(xs) {
     return xs.length < 2 ? (xs[0] ?? "") : `${xs.slice(0, -1).join(", ")}, and ${xs.at(-1)}`;

package/dist/server.d.ts

@@ -1,18 +1,22 @@
-/**
- * The paidfor MCP server. One factory, three transports: stdio (npx @paidfor/mcp),
- * the hosted Streamable HTTP service (index.ts) and the Next.js route at /mcp on the site.
- * The read tools are thin readers of the public JSON API; the verdict logic lives on the site.
- * The paying tools (pay.ts) are added by stdio.ts alone, and only when a wallet is configured.
- */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { REPORT_OUTCOMES } from "./rules.js";
 export * from "./rules.js";
-export declare const VERSION = "0.3.2";
+export declare const VERSION = "0.4.1";
 /** Sent on every request to the index so usage can be counted by channel (never anything else). */
-export declare const CLIENT_HEADER = "mcp/0.3.2";
+export declare const CLIENT_HEADER = "mcp/0.4.1";
 /** What the hosted service (index.ts) sends instead, so the index can count hosted and stdio use apart. */
-export declare const HOSTED_CLIENT_HEADER = "mcp-hosted/0.3.2";
+export declare const HOSTED_CLIENT_HEADER = "mcp-hosted/0.4.1";
+/**
+ * Which client product a hosted session comes from, read from `clientInfo.name` on initialize and nothing else from the
+ * handshake: a product name, never a user. The hosted service appends it to its header (`mcp-hosted/<version>+claude`),
+ * so the index's channel counts split directory traffic by client with no change on the index side.
+ */
+export declare const CLIENT_TAGS: readonly ["claude", "chatgpt", "cursor", "other"];
+export type ClientTag = (typeof CLIENT_TAGS)[number];
+export declare function clientTag(name: unknown): ClientTag;
+export declare const taggedClientHeader: (tag: ClientTag | null) => string;
 export declare const DEFAULT_BASE = "https://paidfor.dev";
-export declare const TOOL_NAMES: readonly ["check_x402_seller", "list_reliable_sellers", "recent_changes"];
+export declare const TOOL_NAMES: readonly ["check_x402_seller", "list_reliable_sellers", "recent_changes", "report_x402_payment"];
 /**
  * The no-account promise, word for word wherever it appears: the server instructions (last line),
  * this package's README, /methodology, /install.md and /privacy on the site.
@@ -27,6 +31,8 @@ export declare const INSTRUCTIONS: string;
  * tools unprompted. stdio and the skill keep INSTRUCTIONS; the tool descriptions are shared by both.
  */
 export declare const HOSTED_INSTRUCTIONS: string;
+/** The first sentence of each read tool description: when to call it. The manifest and the setup page list these as they are. */
+export declare const TOOL_TRIGGERS: Record<(typeof TOOL_NAMES)[number], string>;
 export declare const CHECK_DESCRIPTION: string;
 export declare const LIST_DESCRIPTION: string;
 export declare const CHANGES_DESCRIPTION: string;
@@ -55,4 +61,74 @@ export declare const SERVER_INFO: {
         sizes: string[];
     }[];
 };
+type TelemetryAnswer = {
+    status?: string;
+    error?: string;
+    reason?: string;
+    payer?: string;
+    pay_to?: string;
+    amount_usdc?: string;
+    block?: number;
+    own?: boolean;
+    unattributed_seller?: boolean;
+    verification_url?: string;
+};
+/** The tx_only telemetry row the skill also sends (paidfor-client docs/telemetry.md, "tx_only"); the index reads the rest from Base. */
+export declare function reportPayload(i: {
+    url: string;
+    tx_hash: string;
+    outcome: keyof typeof REPORT_OUTCOMES;
+    quoted_usdc?: string | number;
+    http_status?: number;
+    client: string;
+}): {
+    latency_ms: number;
+    validator_failures: string[];
+    client: string;
+    proof: {
+        network: string;
+        tx_hash: string;
+    };
+    amount_usdc?: string | undefined;
+    path_hash: string;
+    outcome: "ok" | "duplicate" | "non_delivery" | "wrong_goods" | "overcharge";
+    path?: string | undefined;
+    v: number;
+    proof_level: string;
+    host: string;
+};
+/** The index's answer as one sentence and the structured result. */
+export declare function reportResult(httpStatus: number, a: TelemetryAnswer): {
+    sentence: string;
+    reason: null;
+    payer: string | null;
+    pay_to: string | null;
+    amount_usdc: string | null;
+    verification_url: string | null;
+    status: "verified";
+} | {
+    sentence: string;
+    reason: null;
+    payer: string | null;
+    pay_to: string | null;
+    amount_usdc: string | null;
+    verification_url: string | null;
+    status: "pending";
+} | {
+    sentence: string;
+    reason: null;
+    payer: string | null;
+    pay_to: string | null;
+    amount_usdc: string | null;
+    verification_url: string | null;
+    status: "duplicate";
+} | {
+    reason: string;
+    sentence: string;
+    payer: string | null;
+    pay_to: string | null;
+    amount_usdc: string | null;
+    verification_url: string | null;
+    status: "rejected";
+};
 export declare function createServer(opts?: ServerOptions): McpServer;

package/dist/server.js

@@ -4,17 +4,36 @@
  * The read tools are thin readers of the public JSON API; the verdict logic lives on the site.
  * The paying tools (pay.ts) are added by stdio.ts alone, and only when a wallet is configured.
  */
+import { createHash } from "node:crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ListPromptsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
-import { CHANGES_TRIGGER, CHECK_TRIGGERS, CHOOSE_TRIGGER, NEVER_PAY_TWICE, SENDS_ONLY_URL, VERDICT_SENTENCE, cap, listAnd, listOr } from "./rules.js";
+import { CHANGES_TRIGGER, CHECK_TRIGGERS, CHOOSE_TRIGGER, NEVER_PAY_TWICE, REPORT_DESCRIPTION, REPORT_OUTCOMES, REPORT_SENDS, SENDS_ONLY_URL, VERDICT_SENTENCE, cap, listAnd, listOr } from "./rules.js";
 export * from "./rules.js";
-export const VERSION = "0.3.2";
+export const VERSION = "0.4.1";
 /** Sent on every request to the index so usage can be counted by channel (never anything else). */
 export const CLIENT_HEADER = `mcp/${VERSION}`;
 /** What the hosted service (index.ts) sends instead, so the index can count hosted and stdio use apart. */
 export const HOSTED_CLIENT_HEADER = `mcp-hosted/${VERSION}`;
+/**
+ * Which client product a hosted session comes from, read from `clientInfo.name` on initialize and nothing else from the
+ * handshake: a product name, never a user. The hosted service appends it to its header (`mcp-hosted/<version>+claude`),
+ * so the index's channel counts split directory traffic by client with no change on the index side.
+ */
+export const CLIENT_TAGS = ["claude", "chatgpt", "cursor", "other"];
+export function clientTag(name) {
+    const n = typeof name === "string" ? name.toLowerCase() : "";
+    if (n.includes("claude"))
+        return "claude";
+    if (n.includes("chatgpt") || n.includes("openai"))
+        return "chatgpt";
+    if (n.includes("cursor"))
+        return "cursor";
+    return "other";
+}
+export const taggedClientHeader = (tag) => (tag ? `${HOSTED_CLIENT_HEADER}+${tag}` : HOSTED_CLIENT_HEADER);
 export const DEFAULT_BASE = "https://paidfor.dev";
-export const TOOL_NAMES = ["check_x402_seller", "list_reliable_sellers", "recent_changes"];
+export const TOOL_NAMES = ["check_x402_seller", "list_reliable_sellers", "recent_changes", "report_x402_payment"];
 const CATEGORIES = ["inference", "data", "scraping", "compute", "other"];
 /**
  * The no-account promise, word for word wherever it appears: the server instructions (last line),
@@ -30,7 +49,8 @@ export const INSTRUCTIONS = "paidfor rates x402 sellers by paying them and verif
     `${cap(CHOOSE_TRIGGER)}, prefer results from list_reliable_sellers. ` +
     `${cap(CHANGES_TRIGGER)}, call recent_changes. ` +
     `${NEVER_PAY_TWICE} ` +
-    SENDS_ONLY_URL +
+    `${SENDS_ONLY_URL} ` +
+    `After any x402 payment made with any wallet outside this server, call report_x402_payment with the resource URL, the settlement transaction hash and the outcome; it moves no money and sends only ${REPORT_SENDS}.` +
     "\n" +
     NO_ACCOUNT_PROMISE;
 /**
@@ -43,15 +63,23 @@ export const HOSTED_INSTRUCTIONS = "paidfor rates x402 sellers by paying them an
     '"avoid" means the seller failed paid calls (the evidence link shows how), "caution" carries the failure rate, "ok" means no failures across its paid calls, and "unknown" means the index has no data on it. ' +
     "list_reliable_sellers returns sellers with zero failures across at least 30 paid calls, for choosing among sellers. " +
     "recent_changes returns what changed in the index, which is diffed hourly. " +
-    `${SENDS_ONLY_URL}\n` +
+    `${SENDS_ONLY_URL} ` +
+    `report_x402_payment records what came back after a payment the user's own wallet already made, from the resource URL, the settlement transaction hash and the outcome; it moves no money, sends only ${REPORT_SENDS}, and the report counts only once the transaction is verified as a USDC transfer on Base.\n` +
     NO_ACCOUNT_PROMISE;
-export const CHECK_DESCRIPTION = `Call this ${listOr(CHECK_TRIGGERS)}. ` +
+/** The first sentence of each read tool description: when to call it. The manifest and the setup page list these as they are. */
+export const TOOL_TRIGGERS = {
+    check_x402_seller: `Call this ${listOr(CHECK_TRIGGERS)}.`,
+    list_reliable_sellers: `Call this ${CHOOSE_TRIGGER}, or when the user asks for a safe or reliable API.`,
+    recent_changes: `Call this ${CHANGES_TRIGGER}.`,
+    report_x402_payment: REPORT_DESCRIPTION.split(". ")[0] + ".",
+};
+export const CHECK_DESCRIPTION = `${TOOL_TRIGGERS.check_x402_seller} ` +
     "Returns a verdict (avoid, caution, ok, unknown), one sentence to act on, the seller's paid-call count and failure rate with a 95% interval, " +
     "listed price, modal quote and max overcharge ratio when known, and links to the seller page and raw evidence.";
-export const LIST_DESCRIPTION = `Call this ${CHOOSE_TRIGGER}, or when the user asks for a safe or reliable API. ` +
+export const LIST_DESCRIPTION = `${TOOL_TRIGGERS.list_reliable_sellers} ` +
     "Returns sellers with zero failures across at least 30 paid calls, most-called first. For each: domain, category, paid-call count, " +
     "the 95% upper bound on its failure rate, median quoted price in USDC, USDC paid to it in the last 30 days, when it was last seen, and its paidfor seller page.";
-export const CHANGES_DESCRIPTION = `Call this ${CHANGES_TRIGGER}. ` +
+export const CHANGES_DESCRIPTION = `${TOOL_TRIGGERS.recent_changes} ` +
     "Returns recent changes, newest first: verdict changes, new failures by type, moved quotes, changed pay-to addresses, sellers added or reaching 30 paid calls, published seller replies, " +
     "the operator-reported series maturing or disagreeing with ours. Each change has its time, type, seller domain, seller page and type-specific details (for example the old and new quote).";
 /** Advertised on initialize (Implementation in the MCP schema) for clients and directories. */
@@ -109,7 +137,54 @@ const CHANGES_OUTPUT = {
         data: z.record(z.string(), z.unknown()).describe("Type-specific details"),
     })),
 };
-/** The read tools only read the public index; the directories ask for these hints. */
+const REPORT_OUTPUT = {
+    status: z.enum(["verified", "pending", "duplicate", "rejected"]).describe("verified: counted once folded in (minutes); pending: checked on Base again within minutes; duplicate: this transaction was already reported; rejected: not counted, see reason"),
+    sentence: z.string().describe("The result in one sentence"),
+    reason: z.string().nullable().describe("Why a report was rejected; null otherwise"),
+    payer: z.string().nullable().describe("The paying wallet, read from the transaction (never from the report)"),
+    pay_to: z.string().nullable(),
+    amount_usdc: z.string().nullable().describe("USDC moved, read from the transaction"),
+    verification_url: z.string().nullable(),
+};
+/** The longest plain path sent; a longer one goes as its hash only. */
+const MAX_REPORT_PATH = 512;
+/** The tx_only telemetry row the skill also sends (paidfor-client docs/telemetry.md, "tx_only"); the index reads the rest from Base. */
+export function reportPayload(i) {
+    const u = new URL(i.url);
+    const path = u.pathname || "/";
+    const quoted = i.quoted_usdc === undefined ? undefined : Number(i.quoted_usdc);
+    return {
+        v: 2,
+        proof_level: "tx_only",
+        host: u.hostname.toLowerCase(),
+        ...(path.length <= MAX_REPORT_PATH ? { path } : {}),
+        path_hash: createHash("sha256").update(path.replace(/\/$/, "") || "/").digest("hex"),
+        outcome: i.outcome,
+        ...(quoted !== undefined && Number.isFinite(quoted) && quoted > 0 ? { amount_usdc: quoted.toFixed(6) } : {}),
+        latency_ms: 0,
+        validator_failures: i.http_status !== undefined && (i.http_status < 200 || i.http_status > 299) ? [`http_status:${i.http_status}`] : [],
+        client: i.client,
+        proof: { network: "eip155:8453", tx_hash: i.tx_hash.toLowerCase() },
+    };
+}
+/** The index's answer as one sentence and the structured result. */
+export function reportResult(httpStatus, a) {
+    const base = { reason: null, payer: a.payer ?? null, pay_to: a.pay_to ?? null, amount_usdc: a.amount_usdc ?? null, verification_url: a.verification_url ?? null };
+    if (httpStatus === 202 && a.status === "verified") {
+        const extra = [
+            a.own ? "it is one of paidfor's own wallets, so it is kept apart from the operator series" : null,
+            a.unattributed_seller ? "the seller is not in the index yet, so the payment is kept unattributed and the seller is queued for measurement" : null,
+        ].filter(Boolean);
+        return { status: "verified", ...base, sentence: `Accepted and verified: ${a.amount_usdc} USDC from ${a.payer} to ${a.pay_to} in Base block ${a.block}${extra.length ? `; ${extra.join("; ")}` : ""}.` };
+    }
+    if (httpStatus === 202)
+        return { status: "pending", ...base, sentence: `Accepted pending verification: the transaction is not readable on Base yet and is checked again within minutes (${a.verification_url}).` };
+    if (httpStatus === 200 && a.status === "duplicate")
+        return { status: "duplicate", ...base, sentence: `Already reported: this transaction is in the index once and was not counted again (${a.verification_url}).` };
+    const why = (a.error ?? `HTTP ${httpStatus}`).replace(/^not accepted: /, "");
+    return { status: "rejected", ...base, reason: a.reason ?? why, sentence: `Rejected: ${why}.` };
+}
+/** The read tools only read the public index; the directories ask for these hints, and for the title repeated as annotations.title. */
 const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
 async function getJsonAs(url, client = CLIENT_HEADER) {
     const res = await fetch(url, { headers: { Accept: "application/json", "User-Agent": `paidfor-mcp/${VERSION}`, "X-Paidfor-Client": client } });
@@ -124,10 +199,16 @@ export function createServer(opts = {}) {
     const base = (opts.baseUrl ?? process.env.PAIDFOR_API_BASE ?? process.env.PAIDFOR_URL ?? DEFAULT_BASE).replace(/\/$/, "");
     const getJson = (url) => getJsonAs(url, opts.clientHeader);
     const server = new McpServer(SERVER_INFO, { instructions: opts.instructions ?? INSTRUCTIONS });
+    // No resources, templates or prompts, but answer the list calls with empty lists instead of
+    // "Method not found": directory scanners (ChatGPT's looks for widget resources) fail the scan otherwise.
+    server.server.registerCapabilities({ resources: {}, prompts: {} });
+    server.server.setRequestHandler(ListResourcesRequestSchema, () => ({ resources: [] }));
+    server.server.setRequestHandler(ListResourceTemplatesRequestSchema, () => ({ resourceTemplates: [] }));
+    server.server.setRequestHandler(ListPromptsRequestSchema, () => ({ prompts: [] }));
     server.registerTool("check_x402_seller", {
         title: "Check an x402 seller before paying",
         description: CHECK_DESCRIPTION,
-        annotations: READ_ONLY,
+        annotations: { ...READ_ONLY, title: "Check an x402 seller before paying" },
         inputSchema: { url: z.string().min(1).describe("x402 resource URL, or a bare seller domain such as api.example.com") },
         outputSchema: CHECK_OUTPUT,
     }, async ({ url }) => {
@@ -157,7 +238,7 @@ export function createServer(opts = {}) {
     server.registerTool("list_reliable_sellers", {
         title: "List reliable pay-per-call API sellers",
         description: LIST_DESCRIPTION,
-        annotations: READ_ONLY,
+        annotations: { ...READ_ONLY, title: "List reliable pay-per-call API sellers" },
         inputSchema: {
             category: z.enum(CATEGORIES).optional().describe("Kind of service to list sellers for; omit to list every kind"),
             limit: z.number().int().min(1).max(500).optional().describe("How many sellers to return, most-called first; 50 when omitted"),
@@ -177,7 +258,7 @@ export function createServer(opts = {}) {
     server.registerTool("recent_changes", {
         title: "Recent changes to x402 sellers",
         description: CHANGES_DESCRIPTION,
-        annotations: READ_ONLY,
+        annotations: { ...READ_ONLY, title: "Recent changes to x402 sellers" },
         inputSchema: {
             host: z.string().min(1).optional().describe("Seller to show changes for, as a bare domain such as api.example.com; omit for every seller"),
             since: z.string().min(1).optional().describe("Show only changes after this time, in ISO 8601 (such as the generated_at of a verdict you already have); omit for the latest changes"),
@@ -197,5 +278,34 @@ export function createServer(opts = {}) {
             : `No changes${host ? ` for ${host}` : ""}${since ? ` since ${since}` : ""}. The index is diffed hourly.`;
         return { content: [{ type: "text", text: `${head}\n\n${JSON.stringify(rows, null, 2)}` }], structuredContent: { count: r.count, events: rows } };
     });
+    server.registerTool("report_x402_payment", {
+        title: "Report an x402 payment outcome",
+        description: REPORT_DESCRIPTION,
+        // It writes one row to the index (not read-only), changes nothing else (not destructive), and the same tx_hash never makes a second row.
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true, title: "Report an x402 payment outcome" },
+        inputSchema: {
+            url: z.string().url().describe("The x402 resource URL that was paid for"),
+            tx_hash: z.string().regex(/^0x[0-9a-fA-F]{64}$/).describe("The settlement transaction hash on Base: the `transaction` field of the seller's PAYMENT-RESPONSE or X-PAYMENT-RESPONSE header (base64 JSON)"),
+            outcome: z.enum(Object.keys(REPORT_OUTCOMES)).describe(`What came back: ${Object.entries(REPORT_OUTCOMES).map(([k, v]) => `${k} (${v})`).join(", ")}`),
+            quoted_usdc: z.union([z.number().positive(), z.string().regex(/^\d{1,12}(\.\d{1,6})?$/)]).optional().describe("The price the 402 quoted, in USDC, if known"),
+            http_status: z.number().int().min(100).max(599).optional().describe("The HTTP status of the paid response, if known"),
+        },
+        outputSchema: REPORT_OUTPUT,
+    }, async ({ url, tx_hash, outcome, quoted_usdc, http_status }) => {
+        opts.onToolCall?.("report_x402_payment");
+        const client = opts.clientHeader ?? CLIENT_HEADER;
+        const res = await fetch(`${base}/v1/telemetry`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Accept: "application/json", "User-Agent": `paidfor-mcp/${VERSION}`, "X-Paidfor-Client": client },
+            body: JSON.stringify(reportPayload({ url, tx_hash, outcome, quoted_usdc, http_status, client })),
+            redirect: "error",
+            signal: AbortSignal.timeout(30_000),
+        });
+        const a = (await res.json().catch(() => ({})));
+        if (res.status >= 500)
+            throw new Error(`${base}/v1/telemetry returned HTTP ${res.status}${a.error ? `: ${a.error}` : ""}; nothing was recorded, try again later`);
+        const r = reportResult(res.status, a);
+        return { content: [{ type: "text", text: r.sentence }], structuredContent: r };
+    });
     return server;
 }

package/dist/setup.d.ts

@@ -0,0 +1,48 @@
+export declare const HOSTED_URL = "https://mcp.paidfor.dev/mcp";
+export declare const SETUP_URL = "https://paidfor.dev/install";
+export declare const SKILL_URL = "https://paidfor.dev/skill.md";
+export declare const PRIVACY_URL = "https://paidfor.dev/privacy";
+export declare const MANIFEST_URL = "https://paidfor.dev/.well-known/mcp.json";
+export declare const AGENT_SETUP = "Tell your agent to read https://paidfor.dev/skill.md";
+/** What the hosted transports put in X-Paidfor-Client on every call to the index (taggedClientHeader: mcp-hosted/<version>+<client tag>). */
+export declare const CLIENT_HEADER_NOTE = "Every call the server makes to the index carries X-Paidfor-Client: mcp-hosted/<version>+<client>, so use can be counted by channel; <client> is your client product (claude, chatgpt, cursor or other, from its name on initialize), never you.";
+export declare const claudeCodeCommand: (url: string) => string;
+export declare const cursorServer: (url: string) => {
+    url: string;
+};
+export declare const cursorDeepLink: (url: string) => string;
+export declare const cursorConfig: (url: string) => string;
+/**
+ * True when the Accept header ranks text/html above JSON, which is a browser opening the URL. Anything else
+ * (no header, *\/*, application/json, text/event-stream, the MCP clients' "application/json, text/event-stream")
+ * keeps the JSON status body or the MCP transport.
+ */
+export declare function prefersHtml(accept: string | null | undefined): boolean;
+export type SetupPageOptions = {
+    /** The URL this page answers on. The snippets always name HOSTED_URL, as /install does. */
+    endpoint: string;
+    /** Where the JSON status body is for a browser: the same URL with ?format=json. */
+    statusUrl: string;
+};
+/** The page a browser gets from GET on the MCP URL. Plain HTML, no script, the same copy as /install. */
+export declare function setupPageHtml({ endpoint, statusUrl }: SetupPageOptions): string;
+/** Status JSON for a browser that asks: GET <mcp url>?format=json. */
+export declare const wantsJsonFormat: (url: string | undefined) => boolean;
+/**
+ * The manifest's `_meta`, under the registry's publisher-provided key (the one `_meta` key the server.json schema
+ * names). mcp/server.json carries a copy; lib/manifest.test.ts on the site fails when the two differ.
+ */
+export declare const MANIFEST_META: {
+    "io.modelcontextprotocol.registry/publisher-provided": {
+        tools: {
+            name: "check_x402_seller" | "list_reliable_sellers" | "recent_changes" | "report_x402_payment";
+            trigger: string;
+        }[];
+        setup_url: string;
+        setup_page: string;
+        skill_url: string;
+        privacy_url: string;
+        auth: string;
+        no_account: string;
+    };
+};

package/dist/setup.js

@@ -0,0 +1,118 @@
+/**
+ * What a person or a directory sees of the server without speaking MCP: the setup snippets (shared with the site's
+ * /install), the HTML page a browser gets from GET on the MCP URL, and the `_meta` block of the manifest at
+ * paidfor.dev/.well-known/mcp.json. All of it is generated from server.ts and rules.ts, like the tool descriptions.
+ */
+import { DEFAULT_BASE, HOSTED_INSTRUCTIONS, NO_ACCOUNT_PROMISE, TOOL_NAMES, TOOL_TRIGGERS, VERSION } from "./server.js";
+export const HOSTED_URL = "https://mcp.paidfor.dev/mcp";
+export const SETUP_URL = `${DEFAULT_BASE}/install`;
+export const SKILL_URL = `${DEFAULT_BASE}/skill.md`;
+export const PRIVACY_URL = `${DEFAULT_BASE}/privacy`;
+export const MANIFEST_URL = `${DEFAULT_BASE}/.well-known/mcp.json`;
+export const AGENT_SETUP = `Tell your agent to read ${SKILL_URL}`;
+/** What the hosted transports put in X-Paidfor-Client on every call to the index (taggedClientHeader: mcp-hosted/<version>+<client tag>). */
+export const CLIENT_HEADER_NOTE = "Every call the server makes to the index carries X-Paidfor-Client: mcp-hosted/<version>+<client>, so use can be counted by channel; <client> is your client product (claude, chatgpt, cursor or other, from its name on initialize), never you.";
+export const claudeCodeCommand = (url) => `claude mcp add --transport http --scope user paidfor ${url}`;
+export const cursorServer = (url) => ({ url });
+export const cursorDeepLink = (url) => `cursor://anysphere.cursor-deeplink/mcp/install?name=paidfor&config=${encodeURIComponent(Buffer.from(JSON.stringify(cursorServer(url)), "utf8").toString("base64"))}`;
+export const cursorConfig = (url) => JSON.stringify({ mcpServers: { paidfor: cursorServer(url) } }, null, 2);
+/**
+ * True when the Accept header ranks text/html above JSON, which is a browser opening the URL. Anything else
+ * (no header, *\/*, application/json, text/event-stream, the MCP clients' "application/json, text/event-stream")
+ * keeps the JSON status body or the MCP transport.
+ */
+export function prefersHtml(accept) {
+    if (!accept)
+        return false;
+    const q = (type) => {
+        let best = 0;
+        for (const part of accept.split(",")) {
+            const [t, ...params] = part.trim().toLowerCase().split(";");
+            if (t.trim() !== type)
+                continue;
+            const qp = params.map((p) => p.trim()).find((p) => p.startsWith("q="));
+            best = Math.max(best, qp ? Number(qp.slice(2)) || 0 : 1);
+        }
+        return best;
+    };
+    const html = q("text/html");
+    return html > 0 && html > q("application/json") && q("text/event-stream") === 0;
+}
+const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+/** Tailwind v4's neutral scale, the site's tokens (app/globals.css), mirrored for dark the same way. */
+const CSS = `:root{color-scheme:light dark;--bg:#fff;--fg:oklch(20.5% 0 0);--muted:oklch(43.9% 0 0);--line:oklch(92.2% 0 0);--code:oklch(97% 0 0);--link:oklch(87% 0 0)}
+@media (prefers-color-scheme:dark){:root{--bg:#000;--fg:oklch(97% 0 0);--muted:oklch(70.8% 0 0);--line:oklch(26.9% 0 0);--code:oklch(20.5% 0 0);--link:oklch(37.1% 0 0)}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.6 ui-sans-serif,system-ui,sans-serif,"Apple Color Emoji","Segoe UI Emoji";-webkit-font-smoothing:antialiased}
+main{max-width:44rem;margin:0 auto;padding:24px 16px 48px}h1{font-size:1.5rem;font-weight:600;margin:8px 0 4px}h2{font-size:1.05rem;font-weight:600;margin:28px 0 6px}
+p{margin:6px 0}.muted{color:var(--muted);font-size:.9rem}a{color:inherit;text-decoration:underline;text-decoration-color:var(--link);text-underline-offset:2px}a:hover{text-decoration-color:var(--fg)}
+code,pre{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.85em}code{background:var(--code);padding:0 4px;border-radius:4px}
+pre{background:var(--code);border:1px solid var(--line);border-radius:6px;padding:10px 12px;overflow-x:auto;white-space:pre-wrap;overflow-wrap:anywhere}pre code{background:none;padding:0}
+.btn{display:inline-block;border:1px solid var(--fg);border-radius:6px;padding:4px 12px;text-decoration:none;font-size:.9rem;margin:4px 0}
+ul{padding-left:20px;margin:6px 0}li{margin:4px 0}details{border:1px solid var(--line);border-radius:6px;padding:8px 12px;margin-top:8px}summary{cursor:pointer;font-weight:500}
+details p{white-space:pre-wrap;font-size:.9rem}footer{border-top:1px solid var(--line);margin-top:32px;padding-top:12px}`;
+/** The page a browser gets from GET on the MCP URL. Plain HTML, no script, the same copy as /install. */
+export function setupPageHtml({ endpoint, statusUrl }) {
+    const pre = (s) => `<pre><code>${esc(s)}</code></pre>`;
+    const tools = TOOL_NAMES.map((t) => `<li><code>${t}</code>: ${esc(TOOL_TRIGGERS[t].replace(/^Call this /, "call it "))}</li>`).join("");
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>paidfor MCP server</title>
+<meta name="description" content="Set up the paidfor MCP server: check an x402 seller before your agent pays. No account, no key.">
+<link rel="icon" href="${DEFAULT_BASE}/icon.png"><link rel="alternate" type="application/json" href="${esc(MANIFEST_URL)}">
+<style>${CSS}</style></head>
+<body><main>
+<p class="muted"><a href="${DEFAULT_BASE}">paidfor.dev</a> · MCP server ${VERSION}</p>
+<h1>paidfor MCP server</h1>
+<p>It rates x402 sellers by paying them and verifying delivery, so your agent can check a seller before it pays one.</p>
+<p class="muted">${endpoint === HOSTED_URL
+        ? `This is a Streamable HTTP MCP endpoint: <code>${esc(endpoint)}</code>. Add it to your MCP client; opening it in a browser shows this page.`
+        : `<code>${esc(endpoint)}</code> is a Streamable HTTP MCP endpoint serving the same tools as <code>${HOSTED_URL}</code>, the URL the setup below uses.`}</p>
+
+<h2>One line for any agent</h2>
+${pre(AGENT_SETUP)}
+<p class="muted">The skill installs the server where it can and keeps the rules where it cannot.</p>
+
+<h2>Claude Code</h2>
+${pre(claudeCodeCommand(HOSTED_URL))}
+
+<h2>Claude (claude.ai, desktop, mobile)</h2>
+<p>Customize, Connectors, + Add, Add custom connector. Name <code>paidfor</code>, URL:</p>
+${pre(HOSTED_URL)}
+<p class="muted">Choose No sign in. On Team and Enterprise an owner adds it under Organization settings, Connectors.</p>
+
+<h2>Cursor</h2>
+<p><a class="btn" href="${esc(cursorDeepLink(HOSTED_URL))}">Add to Cursor</a></p>
+<p class="muted">Or merge into <code>~/.cursor/mcp.json</code>:</p>
+${pre(cursorConfig(HOSTED_URL))}
+
+<p>VS Code, Windsurf, Codex, ChatGPT and stdio: <a href="${SETUP_URL}">${SETUP_URL.replace("https://", "")}</a>.</p>
+
+<h2>Tools</h2>
+<ul>${tools}</ul>
+<details><summary>Server instructions, as sent on initialize</summary><p>${esc(HOSTED_INSTRUCTIONS)}</p></details>
+
+<h2>No account, no key</h2>
+<p>${esc(NO_ACCOUNT_PROMISE)}</p>
+<p class="muted">${esc(CLIENT_HEADER_NOTE)}</p>
+
+<footer class="muted"><a href="${MANIFEST_URL}">Manifest</a> · <a href="${DEFAULT_BASE}/api">API</a> · <a href="${PRIVACY_URL}">Privacy</a> · <a href="${esc(statusUrl)}">Status JSON</a></footer>
+</main></body></html>
+`;
+}
+/** Status JSON for a browser that asks: GET <mcp url>?format=json. */
+export const wantsJsonFormat = (url) => /[?&]format=json(&|$)/.test(url ?? "");
+/**
+ * The manifest's `_meta`, under the registry's publisher-provided key (the one `_meta` key the server.json schema
+ * names). mcp/server.json carries a copy; lib/manifest.test.ts on the site fails when the two differ.
+ */
+export const MANIFEST_META = {
+    "io.modelcontextprotocol.registry/publisher-provided": {
+        tools: TOOL_NAMES.map((name) => ({ name, trigger: TOOL_TRIGGERS[name] })),
+        setup_url: SETUP_URL,
+        setup_page: HOSTED_URL,
+        skill_url: SKILL_URL,
+        privacy_url: PRIVACY_URL,
+        auth: "none",
+        no_account: NO_ACCOUNT_PROMISE,
+    },
+};

package/dist/stdio.js

@@ -3,28 +3,50 @@
  * `npx @paidfor/mcp`: the stdio server. With PAIDFOR_WALLET_KEY_FILE (or PAIDFOR_WALLET_KEY) set it also
  * registers pay_x402 and wallet_status; without one it is the same read-only server as the hosted one.
  * `paidfor-mcp wallet new` writes a fresh key to ~/.paidfor/wallet.key (mode 600) and prints the address.
+ * `paidfor-mcp wallet register` proves that wallet to a paidfor team (PAIDFOR_TEAM_KEY), so the team's rules apply to it.
  */
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { DEFAULT_BASE, createServer } from "./server.js";
-import { FUND_SENTENCE, WalletConfigError, loadWallet, newWallet, readLimits } from "./wallet.js";
-const [cmd, sub] = process.argv.slice(2);
+import { FUND_SENTENCE, WalletConfigError, loadWallet, newWallet, readLimits, registerWallet } from "./wallet.js";
+const [cmd, sub, ...rest] = process.argv.slice(2);
+const baseUrl = (process.env.PAIDFOR_API_BASE ?? process.env.PAIDFOR_URL ?? DEFAULT_BASE).replace(/\/$/, "");
 if (cmd === "wallet") {
-    if (sub !== "new") {
-        process.stderr.write("usage: paidfor-mcp wallet new\n");
-        process.exit(2);
-    }
+    const usage = "usage: paidfor-mcp wallet new | PAIDFOR_TEAM_KEY=pft_... paidfor-mcp wallet register [--label \"research agent\"]\n";
     try {
-        const { address, file } = await newWallet();
-        process.stdout.write(`${address}\n${FUND_SENTENCE}\n`);
-        process.stderr.write(`key written to ${file} (mode 600); set PAIDFOR_WALLET_KEY_FILE=${file} in your MCP client config\n`);
-        process.exit(0);
+        if (sub === "new") {
+            const { address, file } = await newWallet();
+            process.stdout.write(`${address}\n${FUND_SENTENCE}\n`);
+            process.stderr.write(`key written to ${file} (mode 600); set PAIDFOR_WALLET_KEY_FILE=${file} in your MCP client config\n`);
+            process.exit(0);
+        }
+        if (sub === "register") {
+            // The team key comes from the environment, not an argument: it is a secret, and arguments show in process lists.
+            const teamKey = process.env.PAIDFOR_TEAM_KEY?.trim();
+            if (!teamKey) {
+                process.stderr.write(`paidfor-mcp: PAIDFOR_TEAM_KEY is not set. Make a key on ${baseUrl}/team and run: PAIDFOR_TEAM_KEY=pft_... paidfor-mcp wallet register\n`);
+                process.exit(2);
+            }
+            const at = rest.indexOf("--label");
+            if (at >= 0 && (rest[at + 1] === undefined || rest[at + 1].startsWith("--"))) {
+                process.stderr.write(usage);
+                process.exit(2);
+            }
+            const label = at >= 0 ? rest[at + 1] : "";
+            const r = await registerWallet({ baseUrl, teamKey, label });
+            process.stdout.write(`${r.address}\n`);
+            process.stdout.write(r.already ? "already registered to your team; nothing changed\n" : r.moved ? "registered to your team (it was moved from another team)\n" : "registered to your team\n");
+            if (r.paused)
+                process.stdout.write(`it starts paused: open ${baseUrl}/team, check its limits, untick Paused and save\n`);
+            process.exit(0);
+        }
+        process.stderr.write(usage);
+        process.exit(2);
     }
     catch (e) {
         process.stderr.write(`paidfor-mcp: ${e instanceof Error ? e.message : String(e)}\n`);
         process.exit(1);
     }
 }
-const baseUrl = (process.env.PAIDFOR_API_BASE ?? process.env.PAIDFOR_URL ?? DEFAULT_BASE).replace(/\/$/, "");
 let pay = null;
 let limits = null;
 try {
@@ -40,7 +62,8 @@ catch (e) {
 if (pay && limits) {
     const { INSTRUCTIONS_WITH_PAY, registerPayTools } = await import("./pay.js");
     const server = createServer({ baseUrl, instructions: INSTRUCTIONS_WITH_PAY });
-    await registerPayTools(server, { wallet: pay, limits, baseUrl });
+    // PAIDFOR_FETCH_ALIAS=1 also registers the handler as fetch_paid_url (eval/routing.mjs measures whether the second name helps).
+    await registerPayTools(server, { wallet: pay, limits, baseUrl, fetchAlias: process.env.PAIDFOR_FETCH_ALIAS === "1" });
     await server.connect(new StdioServerTransport());
 }
 else {

package/dist/wallet.d.ts

@@ -22,6 +22,31 @@ export declare function newWallet(home?: string): Promise<{
     address: `0x${string}`;
     file: string;
 }>;
+/** The wallet `wallet new` writes, used by `wallet register` when no key is configured in the environment. */
+export declare const defaultKeyFile: (home?: string) => string;
+/** paidfor refused or could not answer a registration. The message never includes a key. */
+export declare class RegisterError extends Error {
+    name: string;
+}
+export type Registered = {
+    address: `0x${string}`;
+    already: boolean;
+    moved: boolean;
+    paused: boolean;
+};
+/**
+ * `paidfor-mcp wallet register`: proves to a paidfor team that this wallet is the agent's, by signing the challenge
+ * the team's key asks for. The wallet is the configured one, or ~/.paidfor/wallet.key when nothing is configured.
+ * The key signs one message and is sent nowhere; the team key authenticates the two calls.
+ */
+export declare function registerWallet(o: {
+    baseUrl: string;
+    teamKey: string;
+    label?: string;
+    env?: Env;
+    home?: string;
+    fetchFn?: typeof fetch;
+}): Promise<Registered>;
 export type Limits = {
     maxPerCallUsd: number;
     dailyCapUsd: number;

package/dist/wallet.js

@@ -72,6 +72,57 @@ export async function newWallet(home = homedir()) {
     }
     return { address: privateKeyToAccount(key).address, file };
 }
+/** The wallet `wallet new` writes, used by `wallet register` when no key is configured in the environment. */
+export const defaultKeyFile = (home = homedir()) => join(paidforDir(home), "wallet.key");
+/** paidfor refused or could not answer a registration. The message never includes a key. */
+export class RegisterError extends Error {
+    name = "RegisterError";
+}
+/**
+ * `paidfor-mcp wallet register`: proves to a paidfor team that this wallet is the agent's, by signing the challenge
+ * the team's key asks for. The wallet is the configured one, or ~/.paidfor/wallet.key when nothing is configured.
+ * The key signs one message and is sent nowhere; the team key authenticates the two calls.
+ */
+export async function registerWallet(o) {
+    const env = { ...(o.env ?? process.env) };
+    const none = new WalletConfigError("no wallet to register: run `paidfor-mcp wallet new` first, or set PAIDFOR_WALLET_KEY_FILE");
+    if (!env.PAIDFOR_WALLET_KEY_FILE?.trim() && !env.PAIDFOR_WALLET_KEY?.trim()) {
+        const file = defaultKeyFile(o.home);
+        if (!(await stat(file).catch(() => null)))
+            throw none;
+        env.PAIDFOR_WALLET_KEY_FILE = file;
+    }
+    const loaded = await loadWallet(env);
+    if (!loaded)
+        throw none;
+    const f = o.fetchFn ?? fetch;
+    const base = o.baseUrl.replace(/\/$/, "");
+    // The team key travels in a header. Plain http is for a server on this machine only.
+    const u = new URL(base);
+    if (u.protocol !== "https:" && !["localhost", "127.0.0.1", "[::1]"].includes(u.hostname)) {
+        throw new RegisterError(`refusing to send a team key over ${u.protocol.replace(":", "")} to ${u.hostname}; use https`);
+    }
+    const post = async (path, body) => {
+        let res;
+        try {
+            res = await f(`${base}${path}`, { method: "POST", headers: { Authorization: `Bearer ${o.teamKey}`, "Content-Type": "application/json" }, body: JSON.stringify(body) });
+        }
+        catch (e) {
+            throw new RegisterError(`could not reach ${base}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        const j = (await res.json().catch(() => ({})));
+        if (!res.ok)
+            throw new RegisterError(`paidfor answered ${res.status}${typeof j.error === "string" ? `: ${j.error}` : ""}`);
+        return j;
+    };
+    const c = await post("/v1/team/wallets/challenge", { address: loaded.account.address });
+    if (typeof c.message !== "string" || typeof c.token !== "string")
+        throw new RegisterError("paidfor did not return a challenge to sign");
+    const signature = await loaded.account.signMessage({ message: c.message });
+    const r = await post("/v1/team/wallets", { message: c.message, token: c.token, signature, label: o.label ?? "" });
+    const w = (r.wallet ?? {});
+    return { address: (w.address ?? loaded.account.address), already: r.already === true, moved: r.moved === true, paused: w.rules?.paused === true };
+}
 function positive(env, name, dflt) {
     const raw = env[name]?.trim();
     if (!raw)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@paidfor/mcp",
-  "version": "0.3.2",
-  "mcpName": "io.github.sarmadahsan/paidfor",
+  "version": "0.5.0",
+  "mcpName": "dev.paidfor/paidfor",
   "description": "MCP server for the paidfor.dev x402 seller index: check_x402_seller, list_reliable_sellers and recent_changes, plus pay_x402 (stdio, your own wallet)",
   "license": "MIT",
   "type": "module",
@@ -13,7 +13,8 @@
   },
   "main": "./dist/server.js",
   "exports": {
-    ".": "./dist/server.js"
+    ".": "./dist/server.js",
+    "./setup": "./dist/setup.js"
   },
   "files": [
     "dist",
@@ -50,6 +51,8 @@
     "start": "node dist/index.js",
     "dev": "tsc -p tsconfig.json && node dist/index.js",
     "eval": "node --env-file-if-exists=eval/.env eval/run.mjs",
+    "eval:routing": "node --env-file-if-exists=eval/.env eval/routing.mjs",
+    "test": "pnpm build && node --test \"test/*.test.mjs\"",
     "mcpb": "node mcpb/build.mjs"
   }
 }

package/dist/http.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/http.js

@@ -1,49 +0,0 @@
-/**
- * Standalone Streamable HTTP service (Railway / Fly / any Node host). Stateless: one
- * transport per request. GET /health for the platform health check.
- */
-import { createServer as createHttpServer } from "node:http";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { createServer, TOOL_NAMES, VERSION } from "./server.js";
-const port = Number(process.env.PORT ?? 3402);
-const counts = new Map();
-const bump = (k) => counts.set(k, (counts.get(k) ?? 0) + 1);
-const CORS = { "Access-Control-Allow-Origin": "*", "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS", "Access-Control-Allow-Headers": "*" };
-createHttpServer(async (req, res) => {
-    const path = (req.url ?? "/").split("?")[0];
-    if (req.method === "OPTIONS") {
-        res.writeHead(204, CORS);
-        res.end();
-        return;
-    }
-    if (path === "/health") {
-        res.writeHead(200, { "Content-Type": "text/plain", ...CORS });
-        res.end("ok");
-        return;
-    }
-    if (path === "/usage") {
-        res.writeHead(200, { "Content-Type": "application/json", ...CORS });
-        res.end(JSON.stringify(Object.fromEntries(counts)));
-        return;
-    }
-    if (path === "/" || path === "/mcp") {
-        if (req.method === "GET" && !(req.headers.accept ?? "").includes("text/event-stream")) {
-            res.writeHead(200, { "Content-Type": "application/json", ...CORS });
-            res.end(JSON.stringify({ name: "paidfor", version: VERSION, transport: "streamable-http", tools: TOOL_NAMES, usage: "POST JSON-RPC 2.0 to this URL" }));
-            return;
-        }
-        bump("request");
-        for (const [k, v] of Object.entries(CORS))
-            res.setHeader(k, v);
-        const server = createServer({ onToolCall: bump });
-        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
-        res.on("close", () => { void transport.close(); void server.close(); });
-        await server.connect(transport);
-        await transport.handleRequest(req, res);
-        return;
-    }
-    res.writeHead(404, CORS);
-    res.end();
-}).listen(port, () => {
-    console.log(`paidfor MCP (streamable http) listening on :${port}, reading ${process.env.PAIDFOR_URL ?? "https://paidfor.dev"}`);
-});