dpay-mcp

A MCP server for creating, settling, disputing, and refunding escrows on EVM chains.

Quick Start

Configure the MCP server in your client. Restart, then tell your agent what to do.

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "dpay": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@rakelabs/dpay-mcp"],
      "env": {
        "RPC_URL": "${env:RPC_URL}",
        "CHAIN_ID": "${env:CHAIN_ID}",
        "PRIVATE_KEY": "${env:PRIVATE_KEY}",
        "ALLOWED_TOKENS": "${env:ALLOWED_TOKENS}"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "dpay": {
      "command": "npx",
      "args": ["-y", "@rakelabs/dpay-mcp"],
      "env": {
        "RPC_URL": "${RPC_URL}",
        "CHAIN_ID": "${CHAIN_ID}",
        "PRIVATE_KEY": "${PRIVATE_KEY}",
        "ALLOWED_TOKENS": "${ALLOWED_TOKENS}"
      }
    }
  }
}

Done

Restart your client. Ask your agent:

I want to do business on chain, what's your wallet address?

More Client Options

Inline values (less secure)

Quick start — replace with your values:

Claude Desktop:

{
  "mcpServers": {
    "dpay": {
      "command": "npx",
      "args": ["-y", "@rakelabs/dpay-mcp"],
      "env": {
        "RPC_URL": "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY",
        "CHAIN_ID": "1",
        "PRIVATE_KEY": "0x...",
        "ALLOWED_TOKENS": "ETH:0.1:0.01"
      }
    }
  }
}

VS Code:

{
  "servers": {
    "dpay": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@rakelabs/dpay-mcp"],
      "env": {
        "RPC_URL": "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY",
        "CHAIN_ID": "1",
        "PRIVATE_KEY": "0x...",
        "ALLOWED_TOKENS": "ETH:0.1:0.01"
      }
    }
  }
}

Windows

npx can hang on Windows. Use cmd /c instead:

Claude Desktop:

{
  "mcpServers": {
    "dpay": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@rakelabs/dpay-mcp"],
      "env": {
        "RPC_URL": "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY",
        "CHAIN_ID": "1",
        "PRIVATE_KEY": "0x...",
        "ALLOWED_TOKENS": "ETH:0.1:0.01"
      }
    }
  }
}

Other MCP Clients

Use command: "npx" with args: ["-y", "@rakelabs/dpay-mcp"] and pass env vars through your client config.

Development

git clone https://github.com/programmaman/dpay-mcp.git
cd dpay-mcp
npm install

export RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
export CHAIN_ID=1
export PRIVATE_KEY=0x...
export ALLOWED_TOKENS=ETH:0.1:0.01

npm run dev

Agent Prompt Examples

I want to do business on chain, what's your wallet address?

Send 0.01 ETH to 0x70997970C51812dc3A010C7d01b50e0d17dc79C8 with a 1-day settlement window.

The agent handles the rest. Tool definitions describe every action — creating payments, checking status, settling, disputing, refunding. Just tell the agent what you need, or let it do what it wants.

Tools

| Tool | Description | Use case | |------|-------------|----------| | whoami | Returns wallet address, chain ID, factory, and spending limits | Start of session | | eth_create_payment | Creates an ETH escrow | Pay someone in ETH | | erc20_create_payment | Creates an ERC20 escrow and handles approval | Pay someone in USDC or another token | | payment_info | Reads on-chain payment state | Check current status | | raise_dispute | Starts arbitration | Payment is disputed | | submit_evidence | Publishes evidence to IPFS and submits it on-chain | Prove a case in arbitration | | settle | Claims funds after the settlement window | You are the payee and time has passed | | refund | Returns funds to the payer voluntarily | You are the payee and want to refund |

Workflows

Create  whoami -> eth_create_payment or erc20_create_payment
Settle  payment_info -> settle (payee only, after settlement window)
Dispute payment_info -> raise_dispute -> submit_evidence
Refund  payment_info -> refund (payee only)

Configuration

Set these environment variables before starting the server.

Required

• RPC_URL: EVM RPC endpoint
• CHAIN_ID: Chain ID. Use 1 for Ethereum mainnet.
• ALLOWED_TOKENS: Spending limits. Format described below.

Optional

• PRIVATE_KEY: Wallet private key. Omit for a disposable wallet.
• MIN_SETTLEMENT_WINDOW_SEC: Minimum settlement window in seconds.
• FACTORY_ADDRESS: Payment factory contract address. Omit if the factory is known for your chain.
• POLICY_WEBHOOK_URL: URL for external compliance checks. Fail-closed.
• POLICY_WEBHOOK_TOKEN: Bearer token for the policy webhook.
• EVIDENCE_IPFS_ENDPOINT: Remote IPFS endpoint. Omit for in-process Helia.
• EVIDENCE_IPFS_AUTH_TYPE: Auth type: bearer, basic, or none.
• EVIDENCE_IPFS_AUTH_TOKEN: Token for bearer auth.
• EVIDENCE_IPFS_USERNAME: Username for basic auth.
• EVIDENCE_IPFS_PASSWORD: Password for basic auth.
• EVIDENCE_IPFS_HEADERS: Extra HTTP headers as JSON. Example: {"network":"public"}
• EVIDENCE_IPFS_UPLOAD_FIELDS: Multipart fields as JSON. Example: {"network":"public"}
• EVIDENCE_IPFS_FILE_FIELD: Multipart field name for the file blob.
• EVIDENCE_IPFS_GATEWAYS: Comma-separated IPFS gateway URLs for readable links.

ALLOWED_TOKENS format

ALLOWED_TOKENS=ETH:0.1:0.01,0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48:500:100

Each entry is address:session_budget:max_per_tx. Built-in aliases are ETH and USDC.

When ALLOWED_TOKENS is set, the server rejects transactions that:

• use a token not in the list
• exceed the per-transaction limit
• exceed the session budget

The server will not start without ALLOWED_TOKENS. This prevents an agent from spending without limits.

Wallets

If you omit PRIVATE_KEY, the server creates a random wallet on first start. The key is saved to ~/.dpay-mcp/wallet-key. Set PRIVATE_KEY later to reuse the same wallet.

Scripts

| Command | Purpose | |---------|---------| | npm run dev | Start the server with tsx (hot reload) | | npm start | Build and start from compiled JavaScript | | npm run inspector | Open the MCP Inspector UI |

Project Structure

src/
  index.ts                   server startup and tool registration
  dpay-signer.ts             transaction signing and submission
  config-enforcer.ts         spending limit checks
  natural-language-converter.ts  ETH and ERC20 unit conversion
  evidence-client.ts         IPFS evidence publishing (worker thread bridge)
  evidence-worker.ts         Helia worker thread
  payment-store.ts           payment record persistence
  error-format.ts            revert data decoding
  policy-webhook.ts          external compliance check
test/                        tests

License

Apache 2.0