# MCP-Pay

**An HTTP x402 monetization layer on Algorand that lets AI agents pay for MCP tools on a sub-cent, pay-per-call basis.**

## Screenshots

| | |
|---|---|
| ![Landing page](docs/shot1.png) | ![Tool catalog](docs/shot3.png) |
| ![Agent payment settlement](docs/shot4.png) | ![On-chain proof on Lora](docs/shot6.png) |

*(All six captures live in [`docs/`](docs).)*

## Problem

Autonomous AI agents using the Model Context Protocol (MCP) cannot access paid tools: credit cards, API keys, and subscriptions are human workflows. Tool creators have no way to charge per call, and legacy chains are too slow or expensive for machine-to-machine micropayments.

## Solution

MCP-Pay converts any MCP tool into an instantly monetized x402 endpoint on Algorand.

1. An agent discovers tools at `GET /mcp/v1/tools` (free, includes JSON schemas + prices).
2. The agent invokes `POST /mcp/v1/tools/:name/execute` without payment.
3. The server answers `402 Payment Required` with payment metadata (price in USDC, receiver address, network).
4. The agent's local middleware auto-signs an Algorand USDC transfer (ASA 31566704) and retries.
5. The [GoPlausible facilitator](https://facilitator.goplausible.xyz) verifies and settles on-chain (<3.3s finality), the tool executes, and results return in one round-trip.

No accounts. No keys. No humans.

## USP

| Typical paid API | MCP-Pay |
|---|---|
| One hardcoded endpoint | **Tool registry**: any tool becomes a priced service with a schema |
| Docs written for humans | **Agent-native discovery**: agents list, compare, and select tools programmatically |
| Subscriptions / prepaid credits | **True pay-per-call** settled on-chain per request |
| EVM gas kills micropayments | **Algorand**: ~0.001 ALGO fee, 3.3s finality |

## Paid Tools Included

| Tool | What it does | Price |
|---|---|---|
| `web_research` | Reader-mode extraction of any public web page for LLM context | $0.002 |
| `market_data` | Live crypto spot prices from a keyless public feed | $0.001 |
| `contract_audit` | Static heuristic security scan of Solidity source | $0.005 |

## Architecture

```
┌────────────────────────┐
│   AI AGENT (client/)   │  1. GET /mcp/v1/tools      (discovery)
│  auto-paying MCP agent │  2. POST .../execute       → 402 challenge
└───────────┬────────────┘  3. sign USDC txn locally
            │               4. retry + X-PAYMENT header
            ▼
┌────────────────────────┐
│  MCP-PAY SERVER (Hono) │  x402 paymentMiddleware protects each tool route
│  registry + tools/*    │  executes tool only after verified settlement
└───────────┬────────────┘
            ▼
┌────────────────────────┐
│ GOPLAUSIBLE FACILITATOR│  /verify + /settle on Algorand TestNet
│  https://facilitator.  │  USDC (ASA 31566704) transfer
│  goplausible.xyz       │
└────────────────────────┘
```

## Tech Stack

- TypeScript, Hono
- [`@x402/core`, `@x402/avm`, `@x402/hono`, `@x402/fetch`](https://docs.x402.org)
- [`@x402-avm/extensions`](https://dev.algorand.co/resources/x402-on-algorand/) (Bazaar discovery)
- GoPlausible facilitator, Algorand TestNet USDC

## Run Locally

### 1. Prerequisites

- Node.js 18+, pnpm (`npm i -g pnpm`)
- Two funded Algorand TestNet accounts:
  - **Server wallet** (receiver): address only
  - **Agent wallet** (payer): mnemonic, kept local — never committed

Fund via [Lora faucet](https://lora.algokit.io/testnet/fund), opt both into USDC in Lora, then get TestNet USDC from the [Circle faucet](https://faucet.circle.com/) (choose Algorand Testnet).

### 2. Configure

```bash
pnpm install
cp .env.example .env
```

Fill `.env`:

```
AVM_ADDRESS=<server wallet address>          # receiver
AVM_MNEMONIC="<agent 25-word mnemonic>"      # payer, LOCAL ONLY
SERVER_URL=http://localhost:4021
```

### 3. Start server + run agent

```bash
pnpm server        # terminal 1
pnpm agent         # terminal 2: discovery → 402 → auto-pay → result
```

## Live Deployment

Production server running on Railway:

```
https://mcp-pay-production.up.railway.app
```

Try it: `GET /health` or browse `GET /mcp/v1/tools` — then pay with any x402 client.

## Verify On-Chain

Every successful call settles a real TestNet transaction:

- Facilitator dashboard: <https://facilitator.goplausible.xyz/dashboard>
- Lora explorer: <https://lora.algokit.io/testnet>

Verified settlements from actual demo runs:

| Tool | Price | Transaction |
|---|---|---|
| `web_research` | $0.002 | [PNSX3OTXTMP5V7JEDDWD2G3H7KS3R7NTB2DO4RFXNR3URYUCPPPQ](https://lora.algokit.io/testnet/transaction/PNSX3OTXTMP5V7JEDDWD2G3H7KS3R7NTB2DO4RFXNR3URYUCPPPQ) |
| `market_data` | $0.001 | [E4OFWPYIXJNGWRYMAJIA2EZOBAQXZ7HI4UOBOFRZPLLNGPAKMZKA](https://lora.algokit.io/testnet/transaction/E4OFWPYIXJNGWRYMAJIA2EZOBAQXZ7HI4UOBOFRZPLLNGPAKMZKA) |
| `contract_audit` | $0.005 | settled (see facilitator dashboard) |
| `market_data` (production) | $0.001 | [DUITAVSQ3TU7WNHMQSNGHXBHG6MFEIBNYJY5HAYC2NNZVG5244YQ](https://lora.algokit.io/testnet/transaction/DUITAVSQ3TU7WNHMQSNGHXBHG6MFEIBNYJY5HAYC2NNZVG5244YQ) |

## API

| Endpoint | Payment | Description |
|---|---|---|
| `GET /health` | free | liveness |
| `GET /mcp/v1/tools` | free | tool catalog with schemas + prices |
| `POST /mcp/v1/tools/:name/execute` | x402 | execute a tool, pay-per-call |

## Roadmap

- Spend-policy guard: per-agent budgets enforced by the middleware
- Creator dashboard: register your own MCP tool + price in minutes
- Bazaar listing at GoPlausible so any third-party agent can discover MCP-Pay tools