tempo-mcp

Unified invoice + dual-rail payment MCP server. Accept payments via Stripe (fiat) or Tempo (on-chain stablecoin) through a single invoice ID, with built-in x402 payment-gated tools.

What it does

• Dual-rail invoicing — one invoice generates both a Stripe Checkout URL and Tempo on-chain payment instructions
• Payment detection — polls Stripe API and Tempo TransferWithMemo event logs; first rail wins
• x402 payment-gated tools — any MCP tool can be wrapped with a paywall; clients get a -32042 JSON-RPC challenge and retry with payment proof
• Refund routing — automatically routes refunds to Stripe Refund API or on-chain transferWithMemo based on how the invoice was paid
• Settlement reports — aggregated totals per rail for any date range
• Full audit trail — every payment, refund, and challenge is logged

Tools (11)

Invoice lifecycle

Tool	Description
create_invoice	Create invoice with Stripe + Tempo payment options
check_invoice_status	Poll both rails for payment
list_invoices	Filter by status, rail, date, amount
get_payment_details	Normalized payment info regardless of rail

Refund & reporting

Tool	Description
issue_refund	Routes to correct rail automatically
get_settlement_report	Aggregated totals per rail for a date range

Configuration

Tool	Description
configure_stripe	Activate Stripe key (memory only)
configure_tempo_wallet	Activate Tempo wallet (memory only)
get_server_status	Health check: rails, balances, DB stats

x402 payment-gated (demo)

Tool	Price	Description
paid_ping	$0.10	Returns "pong" after payment
premium_market_data	$1.00	Returns market data for a token symbol

x402 protocol

Payment-gated tools follow a challenge-response flow over MCP's JSON-RPC transport:

1. Client calls tool → server returns -32042 error with paymentOptions[]
2. Client picks an option (Tempo or Stripe), fulfills payment
3. Client retries tool with payment proof in _meta["x402/payment-proof"]
4. Server verifies → executes tool → returns result + _meta["x402/settlement"]

Every x402 payment creates a tracked invoice — refunds, reports, and filtering work on gated tool payments too.

Setup

npm install
npm run build

Environment variables

# Optional — can configure at runtime via tools
STRIPE_SECRET_KEY=sk_test_...
TEMPO_PRIVATE_KEY=0x...
TEMPO_RPC_URL=https://rpc.testnet.tempo.xyz
TEMPO_MERCHANT_ADDRESS=0x...
TEMPO_TOKEN_ADDRESS=0x...
DB_PATH=./invoices.db

Claude Code MCP config

Add to .mcp.json in your project:

{
  "mcpServers": {
    "tempo-mcp": {
      "command": "node",
      "args": ["/path/to/tempo-mcp/build/index.js"],
      "env": {
        "STRIPE_SECRET_KEY": "sk_test_...",
        "TEMPO_PRIVATE_KEY": "0x...",
        "TEMPO_MERCHANT_ADDRESS": "0x...",
        "TEMPO_TOKEN_ADDRESS": "0x..."
      }
    }
  }
}

Architecture

src/
├── index.ts              # Entry point — load config, init services, connect stdio
├── server.ts             # McpServer singleton
├── config.ts             # Env var loading + zod validation
├── db/
│   ├── database.ts       # SQLite WAL mode, prepared statements
│   └── migrations.ts     # Schema versioning
├── services/
│   ├── stripe-service.ts # Checkout sessions, status checks, refunds
│   ├── tempo-service.ts  # viem clients, getLogs, transferWithMemo
│   ├── invoice-service.ts# Orchestrator: create, check both rails, refund routing
│   └── report-service.ts # SQL aggregation for settlement reports
├── tools/
│   ├── invoice-tools.ts  # create_invoice, check_invoice_status, list, details
│   ├── refund-tools.ts   # issue_refund
│   ├── report-tools.ts   # get_settlement_report
│   ├── config-tools.ts   # configure_stripe, configure_tempo_wallet, status
│   ├── paid-tools.ts     # x402 demo tools (paid_ping, premium_market_data)
│   └── index.ts          # Barrel
├── x402/
│   ├── types.ts          # PaymentOption, PaymentProof, SettlementConfirmation
│   ├── challenge.ts      # Creates payment challenges + backing invoices
│   ├── verify.ts         # Verifies Tempo tx hash or Stripe session
│   ├── paywall.ts        # Middleware: wraps any tool handler with payment gate
│   └── index.ts          # Barrel
├── types/
│   └── index.ts          # Invoice, ServerContext, shared types
└── utils/
    ├── memo.ts           # keccak256(invoiceId) → bytes32 memo
    └── format.ts         # cents/USD conversion, Tempo amount parsing

Tech

• TypeScript, MCP SDK v1, stdio transport
• SQLite (better-sqlite3) with WAL mode
• Stripe SDK for Checkout Sessions
• viem + Tempo testnet for on-chain payments
• Zod for input validation

License

MIT