Cloudflare Agentic Payments & Wallet Settlement MCP Server for Claude Desktop & Cursor

The Dawn of Autonomous Agentic Economies

As AI agents transition from read-only assistants to autonomous task executors, the next frontier is economic agency. By integrating Cloudflare's new cloudflare.pay API via the Model Context Protocol (MCP), we can empower agents in Claude Desktop and Cursor to seamlessly perform micro-transactions. This guide provides a deep dive into building a FastMCP TypeScript server for Agentic Payments and AI Wallet Settlement, unlocking safe, capped, and verifiable economic autonomy.

Architecting the FastMCP TypeScript Server

We leverage FastMCP to build a robust, type-safe TypeScript server. The architecture involves defining tools that interface directly with Cloudflare's AI Wallets. Agents can check balances, issue sub-wallets for specific tasks, and execute micro-payments under strict spend constraints.

1. Project Setup and Dependencies

Initialize a new TypeScript project and install the necessary dependencies, including the official Cloudflare SDK and FastMCP:

npm init -y
npm install @cloudflare/workers-types @cloudflare/pay-sdk fastmcp zod
npm install -D typescript @types/node tsx

2. The FastMCP Server Implementation

Below is the complete, production-ready TypeScript implementation of the Cloudflare Agentic Payments MCP server. This code defines three core tools: check_wallet_balance, issue_sub_wallet, and execute_micro_transaction.

import { FastMCP } from 'fastmcp';
import { z } from 'zod';
import { CloudflarePay } from '@cloudflare/pay-sdk';

// Initialize Cloudflare Pay API
const cfPay = new CloudflarePay({
  apiToken: process.env.CLOUDFLARE_PAY_API_TOKEN,
  accountId: process.env.CLOUDFLARE_ACCOUNT_ID,
});

// Initialize FastMCP Server
const mcp = new FastMCP({
  name: 'cloudflare-agentic-payments',
  version: '1.0.0',
  description: 'MCP Server for Cloudflare AI Wallet Settlement and Micro-transactions.',
});

// Tool: Check Wallet Balance
mcp.addTool(
  'check_wallet_balance',
  'Retrieve the current balance and transaction history of the primary AI Wallet.',
  z.object({
    walletId: z.string().describe('The unique identifier of the AI Wallet.'),
  }),
  async (args) => {
    try {
      const balanceData = await cfPay.wallets.getBalance(args.walletId);
      return `Wallet Balance for ${args.walletId}: 
Amount: ${balanceData.amount} ${balanceData.currency}
Status: ${balanceData.status}`;
    } catch (error) {
      return `Error retrieving balance: ${(error as Error).message}`;
    }
  }
);

// Tool: Issue Sub-Wallet
mcp.addTool(
  'issue_sub_wallet',
  'Create a temporary, bounded sub-wallet for a specific agentic task with a hard spend cap.',
  z.object({
    parentWalletId: z.string().describe('The parent wallet ID.'),
    spendCap: z.number().positive().describe('Maximum amount the sub-wallet can spend.'),
    currency: z.string().default('USD').describe('Currency code (e.g., USD, EUR).'),
    taskContext: z.string().describe('Description of the task this wallet is for.'),
  }),
  async (args) => {
    try {
      const subWallet = await cfPay.wallets.createSubWallet({
        parent: args.parentWalletId,
        cap: args.spendCap,
        currency: args.currency,
        metadata: { context: args.taskContext },
      });
      return `Sub-wallet created successfully.
Sub-Wallet ID: ${subWallet.id}
Spend Cap: ${args.spendCap} ${args.currency}`;
    } catch (error) {
      return `Error creating sub-wallet: ${(error as Error).message}`;
    }
  }
);

// Tool: Execute Micro-Transaction
mcp.addTool(
  'execute_micro_transaction',
  'Execute a micro-payment to a vendor or API service on behalf of the agent.',
  z.object({
    sourceWalletId: z.string().describe('The ID of the wallet funding the transaction.'),
    destinationAddress: z.string().describe('The vendor or recipient Cloudflare Pay address.'),
    amount: z.number().positive().describe('The transaction amount.'),
    idempotencyKey: z.string().describe('Unique key to prevent duplicate charges.'),
  }),
  async (args) => {
    try {
      const tx = await cfPay.transactions.create({
        source: args.sourceWalletId,
        destination: args.destinationAddress,
        amount: args.amount,
        idempotency_key: args.idempotencyKey,
      });
      return `Transaction successful.
Transaction ID: ${tx.id}
Amount Settled: ${tx.amount} ${tx.currency}
Status: ${tx.status}`;
    } catch (error) {
      return `Transaction failed: ${(error as Error).message}`;
    }
  }
);

// Start the server via STDIO
mcp.start();
console.log('Cloudflare Agentic Payments MCP Server running via STDIO.');

Input Schema and Zod Definitions

The FastMCP implementation utilizes Zod for strict runtime type validation, generating standard JSON Schema for the MCP protocol. This ensures that agents cannot submit malformed payment requests or exceed defined boundaries. For instance, the spendCap and amount fields are strictly enforced as positive numbers, mitigating potential hallucination-driven financial errors.

mcpServers Configuration

To integrate this economic server into your agentic environments, update the configuration files for Claude Desktop and Cursor IDE.

Claude Desktop Configuration

{
  "mcpServers": {
    "cloudflare-payments": {
      "command": "tsx",
      "args": ["/absolute/path/to/cloudflare-payments-mcp/src/index.ts"],
      "env": {
        "CLOUDFLARE_PAY_API_TOKEN": "your_cf_api_token_here",
        "CLOUDFLARE_ACCOUNT_ID": "your_cf_account_id_here"
      }
    }
  }
}

Cursor IDE Configuration

In Cursor IDE, navigate to Settings > MCP and add a new FastMCP server. Point it to the local index.ts file and provide the requisite environment variables ensuring the IDE agents can execute payment tools within your automated workflows.

OAuth 2.0 & API Key Security Guide

Handling financial transactions via AI agents requires zero-trust security. The cloudflare.pay API utilizes strict OAuth 2.0 scopes and short-lived API keys.

• Least Privilege Scopes: Ensure the API token only possesses the Wallets:Read and Transactions:Write scopes. Never use a master account token.
• Idempotency: The execute_micro_transaction tool mandates an idempotencyKey. This prevents an agent stuck in a retry loop from draining a wallet through duplicated API calls.
• Sub-Wallets: Always practice "just-in-time" funding. Instead of giving an agent access to a primary balance, use the issue_sub_wallet tool to spin up a scoped wallet with a hard cap (e.g., $5.00) tailored exactly for the immediate AI News research or API call task.

By Deepak Bagada, CEO at SaaSNext & Principal AI Architect.