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.

npm start

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.

- 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