MCP Pay Server

A standalone implementation of the Model Context Protocol (MCP) server with HTTP+SSE transport, including a basic pre-pay credit system.

Features

• Exposes MCP tools, resources, and prompts
• Supports HTTP+SSE for bidirectional communication
• Implements a simple payment layer using USDC deposits on Base (or Base Sepolia)
• Built with Express, TypeScript, Viem, and Zod

Setup

1. Install dependencies:

   npm install
   

2. Configure Environment Variables: Create a .env file in the root directory (mcp-pay-server/.env) with the following:

   # Required: Public address of the wallet the server will watch for USDC deposits
   SERVER_DEPOSIT_ADDRESS=0xYourServerWalletPublicAddress
   
   # Optional: RPC URL for Base or Base Sepolia (defaults provided)
   # BASE_RPC_URL=https://your-base-rpc-url
   
   # Optional: Port for the server (defaults to 3000)
   # PORT=3001
   

   • SERVER_DEPOSIT_ADDRESS: The public 0x... address the server should monitor for incoming USDC deposits.
   • BASE_RPC_URL: The RPC endpoint for interacting with the Base blockchain (mainnet or Sepolia).
   • PORT: The port the HTTP server will listen on.

Usage

Start the server:

npm start

This will start the MCP server and begin watching for USDC deposits to the configured SERVER_DEPOSIT_ADDRESS.

Payment System Overview

This server uses a pre-pay credit system verified via cryptographic signatures. Clients fetch the payment capabilities separately after connecting.

1. Connect: Client connects to the server.
2. Fetch Capabilities: Client calls the payments/getCapabilities method to receive:
   • The URI of the resource providing deposit information (e.g., mcp-pay://server/payment/info).
   • The name of the tool used for checking balances (e.g., payments_getBalance).
   • A list of tools that require payment and their associated cost (as strings).
3. Deposit Info: Clients read the deposit info resource (URI obtained from capabilities) to get the server's USDC deposit address.
4. Credit: Clients send USDC (on the configured network) to the deposit address. The server monitors this address and credits the sender's account in its internal ledger.
5. Paid Tool Usage: When a client calls a tool identified as paid in the capabilities:
   • It must include __payer (its 0x... address) and __signature (ECDSA signature of the canonical request) in the params.arguments.
   • The server's central middleware verifies the signature and checks the payer's balance against the tool's cost before executing the tool logic.
   • If verification succeeds, the tool executes. If the tool execution is successful, the cost is deducted from the payer's balance.
6. Balance Check: Clients use the balance check tool (name obtained from capabilities) with their payerAddress as an argument. This tool does not require a signature.

Available Endpoints

• POST /mcp - For client requests to the server (requires mcp-session-id header). Handles general MCP methods and payments/getCapabilities.
• GET /mcp - For SSE (Server-Sent Events) stream (requires mcp-session-id header).

Payment Capabilities (Exposed via payments/getCapabilities)

• Deposit Info Resource URI: mcp-pay://server/payment/info (by default)
• Balance Check Tool: payments_getBalance (by default)
• Paid Tools (Example):
  • greet: 0.05 USDC (by default)
  • (Others can be configured)

Available Tools

• greet: A simple greeting tool (Requires payment by default).
• payments_getBalance: Returns the credit balance for the calling wallet (Free).

Available Resources

• mcp-pay://server/payment/info: Returns the server's deposit address.

Development

Build the TypeScript code:

npm run build