@paidfor/mcp 0.4.0 → 0.6.0

package/README.md

@@ -45,7 +45,7 @@ The read tools use the public JSON API (`GET https://paidfor.dev/v1/check`, `/v1
 
 ## Let your agent pay, safely (stdio only)
 
-`pay_x402` pays an x402 seller with **your own wallet**, through `@paidfor/x402-safe-fetch` 0.2.0: it checks the seller on paidfor first and refuses `avoid` sellers, refuses 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), keeps receipts in `~/.paidfor/receipts/`, and reports the outcome with its proof of payment (payer, nonce, pay-to, tx hash) to `https://paidfor.dev/v1/telemetry`, where it is checked on Base. It returns the status, the body (truncated at 64 KB) and a receipt with the amount, pay-to, tx hash and basescan link, the seller verdict at purchase, the validator results and the `verification_url` that shows whether the index verified it.
+`pay_x402` pays an x402 seller with **your own wallet**, through `@paidfor/x402-safe-fetch` 0.4.0: it checks the seller on paidfor first and refuses `avoid` sellers, refuses 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), keeps receipts in `~/.paidfor/receipts/`, and reports the outcome with its proof of payment (payer, nonce, pay-to, tx hash) to `https://paidfor.dev/v1/telemetry`, where it is checked on Base. It returns the status, the body (truncated at 64 KB) and a receipt with the amount, pay-to, tx hash and basescan link, the seller verdict at purchase, the validator results and the `verification_url` that shows whether the index verified it.
 
 **Use a dedicated wallet holding a few dollars, never your main wallet.** There is no custody and no account: the key stays on your machine, is read only to sign, and is never logged, returned by a tool or sent anywhere.
 
@@ -70,6 +70,24 @@ 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`; if the MCP client is configured with a key file elsewhere, set `PAIDFOR_WALLET_KEY_FILE` to that same path for this command too, or it registers the default wallet instead. 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. Written into the command it stays in your shell history; to keep it out, `read -rs PAIDFOR_TEAM_KEY && export PAIDFOR_TEAM_KEY` first and run the command without the prefix. Registering does not configure the server: `pay_x402` still needs `PAIDFOR_WALLET_KEY_FILE` in the MCP client config, as above.
+
+**Ask the team before each payment (0.6.0).** Registering alone does not put payments under the team's rules. Give the server the team key too:
+
+```json
+"env": { "PAIDFOR_WALLET_KEY_FILE": "/Users/you/.paidfor/wallet.key", "PAIDFOR_TEAM_KEY": "pft_..." }
+```
+
+With `PAIDFOR_TEAM_KEY` set, `pay_x402` asks `POST /v1/team/authorize` after its own checks and before it signs, and the local caps still apply. It pays only on an approval, and signs with the approval's reference as the EIP-3009 nonce and its deadline as `validBefore`, so the payment can be matched to the ledger. If the server is unreachable or answers anything but a clear decision, nothing is paid. A decline comes back with the team's reason. A payment waiting for a person comes back with the link to approve it and the `intent_id` to call again with. After a payment the outcome goes to `POST /v1/team/outcome`; a report the server cannot take is kept in `~/.paidfor/team-outcomes/` and sent before the next payment. The key sits in your MCP client's config, so treat that file as a secret. The key cannot change rules, keys or approvals. The agent holds its own wallet key here, so a payment made some other way is not stopped. Stdio only: the hosted server never pays.
+
+**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`) |
@@ -77,6 +95,8 @@ 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_TEAM_KEY` | | with a wallet: ask the team's rules before each payment and report the outcome (`https` only, or a server on this machine); also used by `wallet register` |
+| `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.
 
@@ -104,6 +124,14 @@ 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, `pay-team` team mode against a local seller and a scripted server. 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, and `test/mcp-team.test.ts` runs team mode against the real server code.
+
 ## 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).
@@ -111,3 +139,10 @@ Usage is counted by Manufact's gateway (every `tools/call` with client and sessi
 ## Registry
 
 `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.6.0** (unpublished): team mode. With `PAIDFOR_TEAM_KEY` set, `pay_x402` asks the team before signing, fails closed, signs the approval's nonce and deadline and reports the outcome. Needs `@paidfor/x402-safe-fetch` 0.4.0. The hosted server's tools and instructions are unchanged.
+- **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/pay.d.ts

@@ -1,12 +1,21 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { type Receipt, type SafeNetwork } from "@paidfor/x402-safe-fetch";
+import { type TeamDecision } from "./team.js";
 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 +29,12 @@ 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;
+    /** PAIDFOR_TEAM_KEY: ask the team's rules before every payment and report the outcome. Stdio only. */
+    teamKey?: string;
+    /** Tests only: how long to wait before the second try of an outcome report. */
+    teamRetryDelayMs?: number;
 };
 /** 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 +42,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 +58,20 @@ 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;
+/** What pay_x402 says when the team's rules, not the seller or the local caps, stop a payment. Nothing was paid in any of these. */
+export declare function teamRefusal(d: Exclude<TeamDecision, {
+    kind: "approve";
+}>, intentId: string, limits: unknown): {
+    isError?: boolean | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
 export declare function truncateBody(body: string): {
     body: string;
     note: string | null;

package/dist/pay.js

@@ -3,30 +3,45 @@
  * user's own wallet and report the verified outcome to the index. Only stdio.ts imports this module;
  * the hosted service (index.ts) and the site's /mcp route never do, because they never hold a key.
  */
+import { randomUUID } from "node:crypto";
 import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { PaymentRefusedError, SafeFetchError, safeFetch } from "@paidfor/x402-safe-fetch";
 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 { TeamClient, outcomeFor } from "./team.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 by itself (report_x402_payment is not needed after it). 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 +55,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 +67,38 @@ 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.`;
+}
+/** What pay_x402 says when the team's rules, not the seller or the local caps, stop a payment. Nothing was paid in any of these. */
+export function teamRefusal(d, intentId, limits) {
+    const res = (head, detail, isError = false) => text(`${head}\n\n${json({ ...detail, paid: false, intent_id: intentId, limits })}`, isError);
+    switch (d.kind) {
+        case "decline":
+            return res(`Declined by your team's rules: ${d.message}\nNothing was paid.`, { refused: "team_decline", reason: d.reason, ...(d.retry_after !== undefined ? { retry_after: d.retry_after } : {}) });
+        case "needs_approval":
+            return res(`A person has to approve this payment before it can be made. Nothing was paid.\nGive the user this link: ${d.approve_url}\nAfter they approve it, call pay_x402 again with intent_id "${intentId}". The request waits until ${d.expires_at}.${d.message ? ` ${d.message}` : ""}`, { refused: "team_needs_approval", approve_url: d.approve_url, expires_at: d.expires_at });
+        case "already_settled":
+            return res(`This purchase was already paid (settlement ${d.settlement_ref}, outcome ${d.outcome}); nothing was paid again. If this is a new purchase, call again with a new intent_id.`, { refused: "team_already_settled", settlement_ref: d.settlement_ref, outcome: d.outcome });
+        case "failed":
+            return res(`The team's rules could not be checked, so nothing was paid: ${d.message}\nCalling again with intent_id "${intentId}" is safe.`, { refused: "team_authorize_failed" }, true);
+    }
+}
 export function truncateBody(body) {
     const buf = Buffer.from(body, "utf8");
     if (buf.byteLength <= BODY_LIMIT_BYTES)
@@ -71,19 +119,18 @@ 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, title: "Pay an x402 seller safely" },
-        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 team = o.teamKey ? new TeamClient({ baseUrl: base, teamKey: o.teamKey, dir, ...(o.fetch ? { fetch: o.fetch } : {}), warn: logger.warn, ...(o.teamRetryDelayMs !== undefined ? { retryDelayMs: o.teamRetryDelayMs } : {}) }) : null;
+    if (team)
+        void team.flush();
+    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);
@@ -96,6 +143,20 @@ export async function registerPayTools(server, o) {
             spent_today_usdc: fromMicro(spent),
             ...(max_usd !== undefined && max_usd > o.limits.maxPerCallUsd ? { note: `max_usd ${max_usd} is above PAIDFOR_MAX_PER_CALL_USD; capped at ${o.limits.maxPerCallUsd}` } : {}),
         };
+        // Team mode needs the id before the first call: a person's approval is claimed by asking again with the same one.
+        const intentId = intent_id ?? (team ? randomUUID() : undefined);
+        const asked = {};
+        /** Say what happened to an approved payment. Undefined when the server approved nothing. */
+        const settle = async (r) => {
+            const d = asked.decision;
+            if (!team || d?.kind !== "approve")
+                return undefined;
+            if (!r) {
+                logger.warn(`paidfor-mcp: no receipt for approved intent ${intentId}, so no outcome was reported; the approval keeps counting against the budgets`);
+                return undefined;
+            }
+            return team.report(outcomeFor(r, address, d.auth_ref));
+        };
         const sf = safeFetch(o.wallet.account, {
             maxPerCallUsd: cap,
             maxOverListedRatio: 1.1,
@@ -106,35 +167,57 @@ export async function registerPayTools(server, o) {
             logger,
             ...(o.network ? { network: o.network } : {}),
             ...(o.fetch ? { fetch: o.fetch } : {}),
+            ...(team
+                ? {
+                    authorize: async (q) => {
+                        const d = await team.authorize({ wallet: q.payer, intent_id: q.intentId, resource_url: q.url, pay_to: q.payTo, amount_atomic: q.amountAtomic, network: q.network, asset: q.asset, scheme: q.scheme, protocol: "x402" });
+                        asked.decision = d;
+                        return d.kind === "approve" ? { approve: true, nonce: d.auth_ref, validBefore: d.valid_before } : { approve: false, message: d.message };
+                    },
+                }
+                : {}),
         });
         try {
-            const res = await sf(url, { method: method ?? "GET", headers, body }, { intentId: intent_id });
+            // Owed reports go first: until the server has them it answers the same purchase with pending_settlement.
+            await team?.flush();
+            const res = await sf(url, { method: method ?? "GET", headers, body }, { intentId });
             const r = res.receipt;
             if (r.paid && !r.replayed)
                 await ledger.add(toMicro(r.amount_usdc));
+            const teamReport = await settle(r);
             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}.`;
-            return text(`${head}\n\n${json({ status: res.status, receipt: receiptSummary(r), limits, ...(note ? { body_note: note } : {}) })}\n\n--- response body ---\n${out}`);
+            return text(`${head}\n\n${json({ status: res.status, receipt: receiptSummary(r), limits, ...(teamReport ? { team_outcome_report: teamReport } : {}), ...(note ? { body_note: note } : {}) })}\n\n--- response body ---\n${out}`);
         }
         catch (e) {
+            if (asked.decision && asked.decision.kind !== "approve" && e instanceof PaymentRefusedError && e.code === "refused_authorize") {
+                return teamRefusal(asked.decision, e.receipt?.intent_id ?? intentId, limits);
+            }
+            const teamReport = await settle(e instanceof SafeFetchError ? e.receipt : undefined);
+            const reported = teamReport ? { team_outcome_report: teamReport } : {};
             if (e instanceof PaymentRefusedError) {
                 const why = e.code === "refused_max_per_call" && dailyBinds
                     ? `refused: today's cap of ${o.limits.dailyCapUsd} USD (PAIDFOR_DAILY_CAP_USD) leaves ${fromMicro(Math.max(leftMicro, 0))} USDC. ${e.message}`
                     : e.code === "refused_max_per_call"
                         ? `refused: the quote is above this call's cap of ${cap} USD (max_usd, capped by PAIDFOR_MAX_PER_CALL_USD ${o.limits.maxPerCallUsd}). ${e.message}`
                         : `refused: ${e.message}`;
-                return text(`${why}\nNothing was paid.\n\n${json({ refused: e.code, paid: false, seller_url: e.sellerUrl ?? e.receipt?.seller.seller_url ?? null, intent_id: e.receipt?.intent_id ?? intent_id ?? null, limits })}`);
+                return text(`${why}\nNothing was paid.\n\n${json({ refused: e.code, paid: false, seller_url: e.sellerUrl ?? e.receipt?.seller.seller_url ?? null, intent_id: e.receipt?.intent_id ?? intentId ?? null, limits, ...reported })}`);
             }
             if (e instanceof SafeFetchError) {
-                return text(`${e.code}: ${e.message}\n\n${json({ error: e.code, paid: e.receipt?.paid ?? false, receipt: e.receipt ? receiptSummary(e.receipt) : null, limits })}`, true);
+                return text(`${e.code}: ${e.message}\n\n${json({ error: e.code, paid: e.receipt?.paid ?? false, receipt: e.receipt ? receiptSummary(e.receipt) : null, limits, ...reported })}`, true);
             }
             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,
@@ -160,6 +243,7 @@ export async function registerPayTools(server, o) {
             max_per_call_usd: o.limits.maxPerCallUsd,
             daily_cap_usd: o.limits.dailyCapUsd,
             spent_today_usdc: fromMicro(spent),
+            ...(team ? { team_mode: true } : {}),
         };
         return text(`${usdc === null ? "Balance unavailable" : `${usdc} USDC on Base`} at ${address}.\n\n${json(s)}`);
     });

package/dist/rules.d.ts

@@ -40,6 +40,16 @@ export declare const REPORT_OUTCOMES: {
 };
 /** 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

@@ -45,6 +45,19 @@ export const REPORT_OUTCOMES = {
 };
 /** 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,11 +1,11 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { REPORT_OUTCOMES } from "./rules.js";
 export * from "./rules.js";
-export declare const VERSION = "0.4.0";
+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.4.0";
+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.4.0";
+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`),

package/dist/server.js

@@ -10,7 +10,7 @@ import { ListPromptsRequestSchema, ListResourcesRequestSchema, ListResourceTempl
 import { z } from "zod";
 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.4.0";
+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. */

package/dist/stdio.js

@@ -3,28 +3,51 @@
  * `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). With PAIDFOR_TEAM_KEY also set on
+ * the server, pay_x402 asks the team's rules before every payment.
  */
 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 +63,10 @@ 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).
+    // PAIDFOR_TEAM_KEY: every payment asks the team's rules first (docs/team-api.md).
+    const teamKey = process.env.PAIDFOR_TEAM_KEY?.trim() || undefined;
+    await registerPayTools(server, { wallet: pay, limits, baseUrl, fetchAlias: process.env.PAIDFOR_FETCH_ALIAS === "1", ...(teamKey ? { teamKey } : {}) });
     await server.connect(new StdioServerTransport());
 }
 else {

package/dist/team.d.ts

@@ -0,0 +1,80 @@
+import type { Receipt } from "@paidfor/x402-safe-fetch";
+export declare const AUTHORIZE_TIMEOUT_MS = 10000;
+export declare const REPORT_TIMEOUT_MS = 5000;
+export type AuthorizeBody = {
+    wallet: string;
+    intent_id: string;
+    resource_url: string;
+    pay_to: string;
+    amount_atomic: string;
+    network: string;
+    asset: string;
+    scheme: string;
+    protocol: "x402";
+};
+export type TeamDecision = {
+    kind: "approve";
+    auth_ref: string;
+    valid_before: number;
+} | {
+    kind: "decline";
+    reason: string;
+    message: string;
+    retry_after?: number;
+} | {
+    kind: "needs_approval";
+    approve_url: string;
+    expires_at: string;
+    message: string;
+} | {
+    kind: "already_settled";
+    settlement_ref: string;
+    outcome: string;
+    message: string;
+} | {
+    kind: "failed";
+    message: string;
+};
+export type OutcomeBody = {
+    wallet: string;
+    intent_id: string;
+    auth_ref: string;
+    paid: boolean;
+    settlement_ref?: string;
+    outcome?: string;
+    http_status?: number;
+    response_sha256?: string;
+};
+/** sent: the server has it. queued: kept on disk, sent again before the next payment. rejected: the server refused it for good. */
+export type ReportState = "sent" | "queued" | "rejected";
+/** What to report for a payment that was approved, from its receipt. */
+export declare function outcomeFor(r: Receipt, wallet: string, authRef: string): OutcomeBody;
+/** Exported for tests: a 200's body as a decision. Anything not exactly one of the contract's answers is "failed". */
+export declare function readDecision(b: unknown): TeamDecision;
+export declare class TeamClient {
+    private readonly base;
+    private readonly key;
+    private readonly queueDir;
+    private readonly fetchFn;
+    private readonly warn;
+    private readonly retryDelayMs;
+    /** The key travels in a header. Plain http is for a server on this machine only. */
+    private readonly keySafe;
+    constructor(o: {
+        baseUrl: string;
+        teamKey: string;
+        dir: string;
+        fetch?: typeof globalThis.fetch;
+        warn?: (m: string) => void;
+        retryDelayMs?: number;
+    });
+    private post;
+    /** Never throws: anything but a 200 with a readable decision is { kind: "failed" }. */
+    authorize(body: AuthorizeBody): Promise<TeamDecision>;
+    /** One try. "retry" means the server could not take it now; a 4xx will never be taken, so it is not kept. */
+    private send;
+    private queueFile;
+    report(body: OutcomeBody): Promise<ReportState>;
+    /** Send what earlier reports left behind. Stops at the first one the server cannot take now. Never throws. */
+    flush(): Promise<void>;
+}

package/dist/team.js

@@ -0,0 +1,170 @@
+/**
+ * Team mode: the two calls pay_x402 makes around a payment (docs/team-api.md). `authorize` asks before signing and
+ * turns anything but a clean decision into "failed", which pays nothing. `report` says what happened afterwards; a
+ * report the server could not take is kept on disk and sent again, because an approval nobody reports keeps counting
+ * against the budgets. Only pay.ts imports this module.
+ */
+import { createHash } from "node:crypto";
+import { mkdir, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+export const AUTHORIZE_TIMEOUT_MS = 10_000;
+export const REPORT_TIMEOUT_MS = 5_000;
+/** The words the server takes for a paid outcome. */
+const PAID_OUTCOMES = ["ok", "non_delivery", "wrong_goods", "overcharge", "duplicate", "paid_no_response"];
+/** What to report for a payment that was approved, from its receipt. */
+export function outcomeFor(r, wallet, authRef) {
+    const base = { wallet, intent_id: r.intent_id, auth_ref: authRef };
+    // Nothing left this machine, or the seller says its settlement failed: the money did not move.
+    if (!r.paid || r.settlement.parsed?.success === false)
+        return { ...base, paid: false };
+    return {
+        ...base,
+        paid: true,
+        // With no transaction hash the signed nonce is what finds the settlement on chain.
+        settlement_ref: r.tx_hash ?? r.nonce ?? authRef,
+        outcome: r.reported_outcome && PAID_OUTCOMES.includes(r.reported_outcome) ? r.reported_outcome : "non_delivery",
+        ...(r.response ? { http_status: r.response.status } : {}),
+        ...(r.response?.sha256 ? { response_sha256: r.response.sha256 } : {}),
+    };
+}
+const str = (v) => typeof v === "string" && v.length > 0;
+function failedStatus(status, body) {
+    const said = body && typeof body === "object" && str(body.error) ? ` ${body.error.slice(0, 300)}` : "";
+    if (status === 401)
+        return { kind: "failed", message: `paidfor refused the team key; check PAIDFOR_TEAM_KEY.${said}` };
+    if (status === 404)
+        return { kind: "failed", message: `this wallet is not registered to the team; run: paidfor-mcp wallet register.${said}` };
+    return { kind: "failed", message: `paidfor answered HTTP ${status}.${said}` };
+}
+/** Exported for tests: a 200's body as a decision. Anything not exactly one of the contract's answers is "failed". */
+export function readDecision(b) {
+    const bad = { kind: "failed", message: "paidfor's answer could not be read." };
+    if (!b || typeof b !== "object")
+        return bad;
+    const d = b;
+    const message = str(d.message) ? d.message : "";
+    switch (d.decision) {
+        case "approve":
+            return str(d.auth_ref) && typeof d.valid_before === "number" ? { kind: "approve", auth_ref: d.auth_ref, valid_before: d.valid_before } : bad;
+        case "decline":
+            return str(d.reason) ? { kind: "decline", reason: d.reason, message: message || d.reason, ...(typeof d.retry_after === "number" ? { retry_after: d.retry_after } : {}) } : bad;
+        case "needs_approval":
+            return str(d.approve_url) && str(d.expires_at) ? { kind: "needs_approval", approve_url: d.approve_url, expires_at: d.expires_at, message } : bad;
+        case "already_settled":
+            return { kind: "already_settled", settlement_ref: str(d.settlement_ref) ? d.settlement_ref : "unknown", outcome: str(d.outcome) ? d.outcome : "unknown", message };
+        default:
+            return bad;
+    }
+}
+export class TeamClient {
+    base;
+    key;
+    queueDir;
+    fetchFn;
+    warn;
+    retryDelayMs;
+    /** The key travels in a header. Plain http is for a server on this machine only. */
+    keySafe;
+    constructor(o) {
+        this.base = o.baseUrl.replace(/\/$/, "");
+        this.key = o.teamKey;
+        this.queueDir = join(o.dir, "team-outcomes");
+        this.fetchFn = o.fetch ?? globalThis.fetch;
+        this.warn = o.warn ?? (() => undefined);
+        this.retryDelayMs = o.retryDelayMs ?? 250;
+        const u = new URL(this.base);
+        this.keySafe = u.protocol === "https:" || ["localhost", "127.0.0.1", "[::1]"].includes(u.hostname);
+    }
+    post(path, body, timeoutMs) {
+        return this.fetchFn(`${this.base}${path}`, {
+            method: "POST",
+            headers: { "content-type": "application/json", authorization: `Bearer ${this.key}` },
+            body: JSON.stringify(body),
+            redirect: "error", // the key goes to the configured origin and nowhere else
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    /** Never throws: anything but a 200 with a readable decision is { kind: "failed" }. */
+    async authorize(body) {
+        if (!this.keySafe)
+            return { kind: "failed", message: `refusing to send the team key to ${this.base}; use https.` };
+        let res;
+        try {
+            res = await this.post("/v1/team/authorize", body, AUTHORIZE_TIMEOUT_MS);
+        }
+        catch {
+            return { kind: "failed", message: "paidfor could not be reached." };
+        }
+        let parsed = null;
+        try {
+            parsed = await res.json();
+        }
+        catch {
+            /* an unreadable body is handled below */
+        }
+        return res.status === 200 ? readDecision(parsed) : failedStatus(res.status, parsed);
+    }
+    /** One try. "retry" means the server could not take it now; a 4xx will never be taken, so it is not kept. */
+    async send(body) {
+        if (!this.keySafe)
+            return "retry";
+        try {
+            const res = await this.post("/v1/team/outcome", body, REPORT_TIMEOUT_MS);
+            void res.body?.cancel().catch(() => undefined);
+            if (res.ok)
+                return "sent";
+            if (res.status >= 400 && res.status < 500 && res.status !== 408 && res.status !== 429) {
+                this.warn(`paidfor-mcp: the team outcome for intent ${body.intent_id} was refused with HTTP ${res.status}`);
+                return "rejected";
+            }
+            return "retry";
+        }
+        catch {
+            return "retry";
+        }
+    }
+    queueFile(body) {
+        return join(this.queueDir, `${createHash("sha256").update(`${body.intent_id}\n${body.auth_ref}`).digest("hex").slice(0, 40)}.json`);
+    }
+    async report(body) {
+        let r = await this.send(body);
+        if (r === "retry") {
+            await new Promise((d) => setTimeout(d, this.retryDelayMs));
+            r = await this.send(body);
+        }
+        if (r !== "retry")
+            return r;
+        try {
+            await mkdir(this.queueDir, { recursive: true, mode: 0o700 });
+            const file = this.queueFile(body);
+            await writeFile(`${file}.tmp`, JSON.stringify(body), { mode: 0o600 });
+            await rename(`${file}.tmp`, file);
+        }
+        catch (e) {
+            this.warn(`paidfor-mcp: could not keep the team outcome for intent ${body.intent_id}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        return "queued";
+    }
+    /** Send what earlier reports left behind. Stops at the first one the server cannot take now. Never throws. */
+    async flush() {
+        let names;
+        try {
+            names = (await readdir(this.queueDir)).filter((n) => n.endsWith(".json"));
+        }
+        catch {
+            return; // nothing queued yet
+        }
+        for (const name of names) {
+            const file = join(this.queueDir, name);
+            try {
+                const r = await this.send(JSON.parse(await readFile(file, "utf8")));
+                if (r === "retry")
+                    return;
+                await unlink(file);
+            }
+            catch (e) {
+                this.warn(`paidfor-mcp: could not resend ${name}: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+    }
+}

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,6 +1,6 @@
 {
   "name": "@paidfor/mcp",
-  "version": "0.4.0",
+  "version": "0.6.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",
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.2",
-    "@paidfor/x402-safe-fetch": "0.2.0",
+    "@paidfor/x402-safe-fetch": "0.4.0",
     "viem": "^2.57.13",
     "zod": "^4.0.0"
   },
@@ -51,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"}`);
-});