MCP Integration

Enable AI agents like Claude to make stablecoin payments using the Model Context Protocol (MCP).

Overview

The @t402/mcp package provides an MCP server that exposes T402 payment capabilities to AI agents. This enables use cases like:

AI agents paying for API calls
Automated payment workflows
AI-powered financial assistants

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Claude Desktop │────▶│   @t402/mcp     │────▶│   Blockchain    │
│  (MCP Client)   │     │   (MCP Server)  │     │   (EVM/TON/etc) │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Setup

1. Install the Package

npm install -g @t402/mcp

2. Configure Claude Desktop

Edit claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "t402": {
      "command": "npx",
      "args": ["@t402/mcp"],
      "env": {
        "T402_PRIVATE_KEY": "0x...",
        "T402_DEMO_MODE": "true",
        "T402_WDK_SEED_PHRASE": "your twelve word seed phrase here"
      }
    }
  }
}

Setting T402_WDK_SEED_PHRASE enables 5 additional WDK tools (11 total). Without it, only the 6 base tools are available.

3. Restart Claude Desktop

The T402 tools will now be available to Claude.

Available Tools

The MCP server provides 6 base tools, plus 5 additional WDK tools when a seed phrase is configured (11 total).

Base Tools (6)

t402/verify

Verify a payment authorization against the facilitator.

t402/settle

Settle a verified payment on-chain via the facilitator.

t402/supported

List all supported networks, schemes, and signers.

t402/getRequirements

Get payment requirements for a 402-protected resource.

t402/getAllBalances

Check balances across all supported networks.

"What are all my stablecoin balances?"

t402/pay

Execute a stablecoin payment.

"Send 5 USDT0 to 0x1234... on Arbitrum"

WDK Tools (5, requires `T402_WDK_SEED_PHRASE`)

wdk/getWallet

Get WDK wallet address and chain info.

wdk/getBalances

Check balances across all configured WDK chains.

wdk/transfer

Transfer tokens from the WDK wallet.

wdk/swap

Swap tokens via WDK on a given chain.

t402/autoPay

Autonomously fetch a 402-protected resource, sign the payment, and return the content.

Demo Mode

For testing without real transactions:

{
  "mcpServers": {
    "t402": {
      "command": "npx",
      "args": ["@t402/mcp"],
      "env": {
        "T402_DEMO_MODE": "true"
      }
    }
  }
}

In demo mode:

No private key required
Returns simulated balances and transactions
Safe for development and testing

Custom RPC Endpoints

Configure custom RPC URLs for better reliability:

{
  "env": {
    "T402_PRIVATE_KEY": "0x...",
    "T402_RPC_ETHEREUM": "https://eth.llamarpc.com",
    "T402_RPC_BASE": "https://base.llamarpc.com",
    "T402_RPC_ARBITRUM": "https://arb1.arbitrum.io/rpc"
  }
}

Security Best Practices

Use environment variables for private keys
Enable demo mode during development
Set spending limits in your workflows
Monitor transactions via block explorers
Use separate wallets for AI agents

Example Conversations

Checking Balances

User: “What’s my USDT balance?”

Claude: Let me check your balances across all networks.

[Uses t402/getAllBalances]

Here are your current balances:

Ethereum: 150.00 USDT0

Arbitrum: 500.00 USDT0

Base: 75.50 USDT0

Total: 725.50 USDT0

Making Payments

User: “Pay 25 USDT0 to 0xAlice… on Base for the API subscription”

Claude: I’ll send 25 USDT0 to that address on Base.

[Uses t402/pay]

Payment sent successfully!

Amount: 25.00 USDT0

To: 0xAlice…

Network: Base

Transaction: 0x1234…

Cross-Chain Bridging

User: “I need USDT0 on Ethereum but my funds are on Arbitrum”

Claude: I can bridge your USDT0 from Arbitrum to Ethereum. Let me check the fee first.

[Uses t402/getBridgeFee]

The bridge fee is approximately 0.002 ETH (~$5). How much would you like to bridge?

User: “Bridge 200 USDT0”

[Uses t402/bridge]

Bridge transaction initiated!

Amount: 200.00 USDT0

From: Arbitrum

To: Ethereum

Estimated time: ~15 minutes

Transaction: 0x5678…

Troubleshooting

MCP Server Not Found

Ensure @t402/mcp is installed globally:

npm install -g @t402/mcp

Connection Errors

Check that Claude Desktop is properly configured and restarted.

Transaction Failures

Verify sufficient balance for amount + gas
Check network status
Ensure private key has correct permissions

New in v2.9.0

Bazaar Marketplace Tools

Discover and pay for t402-protected services:

Agent: "Find AI inference APIs I can pay for"
> [Uses t402/searchBazaar]
> Found 3 services:
> • GPT-4 Inference API — 0.005 USDC/request on Base
> • Image Generation — 0.002 USDC/request on Base
> • Speech-to-Text — 0.001 USDC/request on Arbitrum

Agent: "Pay for the GPT-4 API"
> [Uses t402/payForService]
> Payment complete! Response received.

Tool	Description
`t402/searchBazaar`	Search marketplace for paid services
`t402/payForService`	Pay for and access a discovered service
`t402/monetizeService`	Generate middleware config to monetize your API

Sign & Verify Tools

Agent: "Sign a message proving I own this wallet"
> [Uses t402/signMessage]
> Signature: 0x3a4b...

Agent: "Verify this signature is from 0xAlice"
> [Uses t402/verifySignature]
> Valid: true — signature matches 0xAlice

Blockchain Indexer

Agent: "Show me recent USDC transfers for 0xMerchant"
> [Uses t402/getTransferHistory]
> Last 5 transfers:
> • 1000 USDC from 0xBuyer1 (2 hours ago)
> • 500 USDC from 0xBuyer2 (5 hours ago)

Historical Prices

Agent: "What's the ETH price trend this week?"
> [Uses t402/getHistoricalPrice]
> ETH/USD 7-day: $3,200 → $3,450 (+7.8%)

Integration with Policy Engine

Use @t402/policy to set spending guardrails for MCP agents:

import { PaymentPolicyEngine } from "@t402/policy";
 
const policy = new PaymentPolicyEngine({
  maxAmountPerPayment: "1000000",    // 1 USDC max per payment
  maxAmountPerSession: "10000000",   // 10 USDC session budget
  maxPaymentsPerHour: 100,
  allowedNetworks: ["eip155:8453", "eip155:42161"],
});

Integration with Observability

Track all MCP payment activity with @t402/observability:

import { PaymentEventCollector, toPrometheusMetrics } from "@t402/observability";
 
const collector = new PaymentEventCollector();
// Expose metrics at /metrics
app.get("/metrics", (req, res) => {
  res.type("text/plain").send(toPrometheusMetrics(collector.getMetrics()));
});

Complete Tool Reference (36+ tools)

Core Payment (12)

t402/getBalance · t402/getAllBalances · t402/pay · t402/payGasless · t402/autoPay · t402/getTokenPrice · t402/getGasPrice · t402/estimatePaymentFee · t402/compareNetworkFees · t402/getBridgeFee · t402/bridge · t402/quoteBridge

WDK Wallet (7)

wdk/getWallet · wdk/getBalances · wdk/transfer · wdk/swap · wdk/quoteSwap · wdk/executeSwap · t402/executeBridgeQuote

Unified (2)

t402/smartPay · t402/paymentPlan

ERC-8004 Identity (3)

erc8004/resolveAgent · erc8004/checkReputation · erc8004/verifyWallet

Bazaar Marketplace (3)

t402/searchBazaar · t402/payForService · t402/monetizeService

Indexer & Signing (4)

t402/signMessage · t402/verifySignature · t402/getTransferHistory · t402/getHistoricalPrice

TON Bridge (5)

t402/tonBridgeQuote · t402/tonBridgeExecute · t402/tonBridgeStatus · t402/tonBridgeBalance · t402/tonBridgeHistory

Cross-Chain Bridge A2A Transport