Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 30 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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&currency=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
Comment thread
jancurn marked this conversation as resolved.
Resolved

# 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&currency=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&currency=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

Expand Down
1 change: 1 addition & 0 deletions docs/vhs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Binary file added docs/vhs/x402.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
96 changes: 96 additions & 0 deletions docs/vhs/x402.tape
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
# mcpc x402 — pay for an MCP server with x402: wallet → challenge → sign → prepaid token → connect → call
#
# X402_DEMO_HOME=<mcpc home with a funded wallet> 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&currency=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
1 change: 1 addition & 0 deletions skills/record-demo/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
Loading