diff --git a/README.md b/README.md index f205e660..29c1643c 100644 --- a/README.md +++ b/README.md @@ -924,26 +924,44 @@ If any request returns HTTP 402, the middleware transparently signs and retries. | Base Mainnet | ✅ Supported | | Base Sepolia testnet | ✅ Supported | -### Paying for Apify with x402 +### Full x402 usage example -To use the Apify MCP server (`mcp.apify.com`) without an Apify account, buy a prepaid, spend-capped Apify API token -from [Apify AGI](https://agi.apify.com) with an x402 payment on Base mainnet, then pass the token as a Bearer token. The wallet must hold USDC on Base (see [Wallet setup](#wallet-setup)): +This end-to-end example pays for the [Apify MCP server](https://mcp.apify.com) with no account or API key. +[Apify](https://apify.com) is the largest and most trusted marketplace of tools for AI agents, +with thousands of ready-made Actors for web scraping, data extraction, and automation. +[Apify AGI](https://agi.apify.com) sells a prepaid, spend-capped API token for an x402 payment +(`exact` scheme, USDC on Base mainnet), and `mcpc` uses that token as a Bearer credential. +Each tool call is then billed against the token's prepaid balance. ```bash -# 1. Fetch the payment challenge (the `payment-required` response header). -PR=$(curl -s -D - -o /dev/null 'https://agi.apify.com/protocols/x402/prepaid-tokens?amount=5¤cy=usd' \ - | awk 'BEGIN{IGNORECASE=1}/^payment-required:/{sub(/\r$/,"");sub(/^[^:]+:[ \t]*/,"");print;exit}') +# 1. Create a wallet (or import one) and send USDC on Base to the printed address or QR code. +# Signing is gasless, so the wallet needs no ETH. +mcpc x402 init + +# Once sent, check that the USDC balance has arrived. +mcpc x402 + +# 2. Fetch the payment challenge for a $1 token, the minimum (the PAYMENT-REQUIRED header). +URL='https://agi.apify.com/protocols/x402/prepaid-tokens?amount=1¤cy=usd' +REQ=$(curl -s -D - -o /dev/null "$URL" | awk -F': ' 'tolower($1)=="payment-required"{print $2}' | tr -d '\r\n') -# 2. Sign it, then resubmit with the signature to receive the token. -SIG=$(mcpc x402 sign "$PR" --scheme exact --json | jq -r .paymentSignature) -TOKEN=$(curl -s 'https://agi.apify.com/protocols/x402/prepaid-tokens?amount=5¤cy=usd' \ - -H "payment-signature: $SIG" | jq -r .token) +# 3. Sign it with the wallet and resubmit; the server settles the payment and returns the token. +SIG=$(mcpc x402 sign "$REQ" --scheme exact --json | jq -r .paymentSignature) +TOKEN=$(curl -s -H "PAYMENT-SIGNATURE: $SIG" "$URL" | jq -r .token) -# 3. Connect with the token. +# 4. Connect with the token and use the server as usual. mcpc connect mcp.apify.com @apify --header "Authorization: Bearer $TOKEN" +mcpc @apify tools-list +mcpc @apify tools-call search-actors keywords:="Google Maps" + +# 5. Check how much of the prepaid balance is left. +curl -s -H "Authorization: Bearer $TOKEN" https://agi.apify.com/prepaid-tokens/balance ``` -See [agi.apify.com/AGENTS.md](https://agi.apify.com/AGENTS.md) for current terms. +![mcpc paying for a prepaid token with x402 and using it with an MCP server](https://raw.githubusercontent.com/apify/mcpc/main/docs/vhs/x402.gif?v=1) + +`mcpc` keeps the token only for the `@apify` session, so save `$TOKEN` if you want to reuse it elsewhere. +See [agi.apify.com/AGENTS.md](https://agi.apify.com/AGENTS.md) for current prices, limits, and terms. ## MCP support diff --git a/docs/vhs/README.md b/docs/vhs/README.md index 65cabcf6..957ab468 100644 --- a/docs/vhs/README.md +++ b/docs/vhs/README.md @@ -34,6 +34,7 @@ replays it, runs the commands against a live MCP server, and renders a GIF. | [`skills.tape`](./skills.tape) | MCP Skills extension: `skills-list` / `skills-get` (SKILL.md + a supporting file) / `resources-directory-read` | Needs a skills server at `mcp.example.com` (see the tape header) | | [`tasks.tape`](./tasks.tape) | MCP Tasks extension: `tools-call --task` (live progress) → `--detach` (task ID via `jq`) → `tasks-get` / `tasks-list` / `tasks-result` | Needs a tasks server at `mcp.example.com` (see the tape header). Width 1280 so the `tasks-list` note fits | | [`security.tape`](./security.tape) | Bare `mcpc connect` skipping a checked-in `.mcp.json` entry that reads `${GITHUB_TOKEN}`, and refusing `-H` | Copies [`security.mcp.json`](./security.mcp.json); the trusted entry needs `mcp.example.com`. Width 1280 so the skip marker and error fit | +| [`x402.tape`](./x402.tape) | Full x402 flow: wallet → payment challenge → `x402 sign` → prepaid token from agi.apify.com → connect `mcp.apify.com` → `tools-call` → balance | Makes a **real 1 USDC payment** per render; needs `X402_DEMO_HOME` with a funded wallet (see the tape header) | ## Recording diff --git a/docs/vhs/x402.gif b/docs/vhs/x402.gif new file mode 100644 index 00000000..1da52a0c Binary files /dev/null and b/docs/vhs/x402.gif differ diff --git a/docs/vhs/x402.tape b/docs/vhs/x402.tape new file mode 100644 index 00000000..856f51cf --- /dev/null +++ b/docs/vhs/x402.tape @@ -0,0 +1,96 @@ +# mcpc x402 — pay for an MCP server with x402: wallet → challenge → sign → prepaid token → connect → call +# +# X402_DEMO_HOME= vhs x402.tape +# +# Follows the "Full x402 usage example" in README.md against agi.apify.com and +# mcp.apify.com. Each render makes a REAL payment of 1 USDC on Base mainnet, so +# the wallet in $X402_DEMO_HOME must hold at least 1 USDC (no ETH needed: the +# exact scheme is a gasless EIP-3009 signature). The minted token is written to +# $X402_DEMO_HOME/token (never shown on screen) so it can be reused or checked. + +Output x402.gif + +Require mcpc +Require jq +Require curl + +Set Shell "bash" +Set FontFamily "JetBrains Mono" +Set FontSize 16 +Set Width 1280 +Set Height 760 +Set Padding 20 +Set TypingSpeed 30ms +Set Theme "Catppuccin Mocha" +Set WindowBar Colorful +Set WindowBarSize 32 +Set BorderRadius 8 +Set CursorBlink true +Set Framerate 24 + +# Hidden setup: the funded wallet's home, prompt styling, and a PROMPT_COMMAND +# that saves the token off-screen once it exists. +Hide +Type 'export MCPC_HOME_DIR="$X402_DEMO_HOME"' +Enter +Type `export PROMPT_COMMAND='[ -n "$TOKEN" ] && printf %s "$TOKEN" > "$MCPC_HOME_DIR/token"'` +Enter +Type 'export PS1="\[\e[1;38;2;25;230;77m\]$\[\e[0m\] \[\e[1;97m\]"' +Enter +Type "trap 'tput sgr0' DEBUG" +Enter +Type "clear" +Enter +Sleep 1000ms +Show + +Type "mcpc x402" +Sleep 300ms +Enter +Sleep 5000ms + +Enter +Type "URL='https://agi.apify.com/protocols/x402/prepaid-tokens?amount=1¤cy=usd'" +Sleep 300ms +Enter +Sleep 500ms + +Type `REQ=$(curl -s -D - -o /dev/null "$URL" | awk -F': ' 'tolower($1)=="payment-required"{print $2}' | tr -d '\r\n')` +Sleep 300ms +Enter +Sleep 2000ms + +Enter +Type `echo "$REQ" | base64 -d | jq '.accepts[0]'` +Sleep 300ms +Enter +Sleep 4000ms + +Enter +Type `SIG=$(mcpc x402 sign "$REQ" --scheme exact --json | jq -r .paymentSignature)` +Sleep 300ms +Enter +Sleep 2000ms + +Type `TOKEN=$(curl -s -H "PAYMENT-SIGNATURE: $SIG" "$URL" | jq -r .token)` +Sleep 300ms +Enter +Sleep 8000ms + +Enter +Type `mcpc connect mcp.apify.com @apify --header "Authorization: Bearer $TOKEN"` +Sleep 300ms +Enter +Sleep 9000ms + +Enter +Type `mcpc @apify tools-call search-actors keywords:="Google Maps" limit:=3` +Sleep 300ms +Enter +Sleep 9000ms + +Enter +Type 'curl -s -H "Authorization: Bearer $TOKEN" https://agi.apify.com/prepaid-tokens/balance | jq' +Sleep 300ms +Enter +Sleep 5000ms diff --git a/skills/record-demo/SKILL.md b/skills/record-demo/SKILL.md index 906fe35d..ca94937c 100644 --- a/skills/record-demo/SKILL.md +++ b/skills/record-demo/SKILL.md @@ -229,6 +229,7 @@ old cached copy. | `skills.tape` | MCP Skills extension: `skills-list` / `skills-get` / `resources-directory-read` against the e2e test server served as `mcp.example.com` | | `tasks.tape` | MCP Tasks extension (2026-07-28): `tools-call --task` with live progress, `--detach` captured through `jq`, then `tasks-get` / `tasks-list` / `tasks-result`, against the same e2e test server as `mcp.example.com` | | `security.tape` | Auto-discovery skipping a checked-in `.mcp.json` entry that reads `${GITHUB_TOKEN}` (fixture: `security.mcp.json`, copied into a `mktemp -d` HOME so no real configs are discovered); needs `mcp.example.com` for the trusted entry | +| `x402.tape` | Full x402 usage example from README.md: funded wallet → sign the agi.apify.com challenge → prepaid token → `mcp.apify.com`. Each render pays **1 USDC for real**; rehearse with a copy cut before the `TOKEN=` line first. The token is saved off-screen to `$X402_DEMO_HOME/token` | All focused tapes follow the same conventions as the hero (bold `$` prompt, bold-white commands, no comments, blank-line separation, `mktemp` home).