Irys x402 MCP Server

A production-ready Model Context Protocol (MCP) server that bridges Irys's programmable datachain with x402 micropayments, enabling AI agents to pay-per-access for verifiable data stored permanently on Irys.

🚀 Deployment Options

Option 1: Self-Hosted (Free, Open Source)

Deploy the MCP server yourself - full control, no monthly fees. Payments route through our PaymentRouter contract (3% commission).

Option 2: Hosted Service ($20/month)

Use our managed API service - no setup required, API keys included, managed infrastructure.

Get Started | Documentation | Deploy Guide

Features

• Data Upload: Upload data to Irys with x402 pricing metadata
• Payment-Gated Access: Access data through x402 payment verification on Base or any EVM chain
• Data Search: Search for available data by title or creator
• Data Listing: List all data by creator address
• Access Tokens: Secure access tokens with expiration after payment verification

Architecture

Two Payment Flows

1. Upload Payment → Irys Network

   • Creator pays Irys (with Base ETH/other tokens) to store data
   • One-time storage cost
   • Data permanently stored on Irys L1 blockchain

2. Access Payment → Creator (x402)

   • AI agent pays creator (via x402 on Base/any chain) to access data
   • Micropayment per access
   • Payment verified on-chain before data access granted

System Diagram

AI Agent (Claude) → MCP Server → Irys L1 (storage) + x402 Payments (Base/ETH)

Installation

npm install

Configuration

Copy .env.example to .env and configure:

cp .env.example .env

Required environment variables:

• IRYS_PRIVATE_KEY: Your Ethereum private key for Irys uploads
• CREATOR_PAYMENT_ADDRESS: Address where you want to receive x402 payments
• IRYS_NETWORK: Network to use (testnet or mainnet)

Optional:

• BASE_SEPOLIA_RPC: RPC URL for payment verification (default: Base Sepolia)
• DATA_REGISTRY_ADDRESS: Smart contract address (if using on-chain registry)

Development

Run in development mode:

npm run dev

Build the project:

npm run build

Run production build:

npm start

MCP Tools

upload_data

Upload data to Irys with x402 pricing.

Parameters:

• data (object, required): Data to upload (will be JSON stringified)
• title (string, required): Title of the data
• description (string, optional): Description
• dataType (string, optional): Type of data (default: "general")
• pricePerAccessInEth (string, required): Price per access in ETH (e.g., "0.001")
• paymentChain (string, optional): Blockchain for payments (default: "base")

Returns:

• dataId: Irys transaction ID
• url: Gateway URL
• pricing: Price and currency information

access_data

Access data from Irys with x402 payment verification.

Parameters:

• dataId (string, required): Irys data ID
• paymentProof (object, optional): Payment proof object with txHash, from, to, amount, chain

Returns:

• If no payment proof: HTTP 402 payment requirement
• If payment proof provided: Data content + access token

search_data

Search for data available on Irys x402 marketplace.

Parameters:

• query (string, required): Search query (searches in titles)
• creator (string, optional): Filter by creator address

Returns:

• results: Array of matching data listings with pricing info

get_data_info

Get detailed information about a specific data listing.

Parameters:

• dataId (string, required): Irys data ID

Returns:

• Complete data metadata including pricing and payment requirements

list_my_data

List all data uploads by the configured creator address.

Parameters: None

Returns:

• listings: Array of all data uploaded by creator
• totalValue: Total value of all listings

Project Structure

irys-x402-mcp/
├── src/
│   ├── index.ts                 # MCP server entry point
│   ├── server/
│   │   ├── MCPServer.ts        # Main server class
│   │   └── tools.ts            # MCP tool definitions
│   ├── irys/
│   │   ├── IrysClient.ts       # Irys operations class
│   │   └── types.ts            # Irys types
│   ├── x402/
│   │   ├── PaymentHandler.ts   # x402 payment verification
│   │   └── types.ts            # Payment types
│   └── utils/
│       ├── config.ts           # Configuration management
│       └── logger.ts           # Logging utility
├── .env.example                # Environment variables template
├── package.json
├── tsconfig.json
└── README.md

Claude Desktop Configuration

Create/edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "irys-x402": {
      "command": "node",
      "args": [
        "/absolute/path/to/irys-x402-mcp/dist/index.js"
      ],
      "env": {
        "IRYS_NETWORK": "testnet",
        "IRYS_PRIVATE_KEY": "your_irys_private_key",
        "BASE_SEPOLIA_RPC": "https://sepolia.base.org",
        "CREATOR_PAYMENT_ADDRESS": "your_payment_address"
      }
    }
  }
}

Usage Examples

Upload Data

// Via MCP tool
{
  "data": { "message": "Hello World" },
  "title": "Test Data",
  "pricePerAccessInEth": "0.001",
  "paymentChain": "base"
}

Access Data (with payment)

// First request returns payment requirement
{
  "dataId": "irys-transaction-id"
}

// After payment, provide proof
{
  "dataId": "irys-transaction-id",
  "paymentProof": {
    "txHash": "0x...",
    "from": "0x...",
    "to": "0x...",
    "amount": "1000000000000000",
    "chain": "base"
  }
}

Testing

Run integration tests:

npm test

Troubleshooting

"Irys client not initialized"

• Ensure IRYS_PRIVATE_KEY is set in .env
• Check wallet has testnet funds: https://faucet.irys.xyz

"Payment verification failed"

• Verify transaction is confirmed (wait for block confirmation)
• Check payment amount >= required amount
• Ensure correct recipient address
• Verify RPC endpoint is responding

"Data not found"

• Check data ID is correct
• Wait for Irys indexing (30-60 seconds)
• Verify upload was successful
• Check Irys gateway: https://gateway.irys.xyz/{dataId}

Resources

• Irys Documentation
• MCP SDK
• x402 Protocol
• Ethers.js Documentation

Revenue Model

This project uses a 3% commission model on all x402 payments:

• Self-hosted users: Free to deploy, but payments route through PaymentRouter contract (3% commission)
• Hosted service users: $20/month subscription + 3% commission on payments
• Commission funds: Platform maintenance, development, and infrastructure

The commission is automatically deducted by the PaymentRouter smart contract before forwarding to data creators.

Deployment

Quick Deploy to DigitalOcean

# 1. Setup server
DROPLET_IP=your.droplet.ip ./scripts/deploy-digitalocean.sh

# 2. Configure Nginx (see scripts/nginx-config.conf)
# 3. Setup SSL
sudo certbot --nginx -d yourdomain.com

Docker Deployment

# Build and run
docker-compose up -d

# Or build manually
docker build -t irys-x402-api .
docker run -p 3001:3001 --env-file .env irys-x402-api

Manual Deployment

See Deployment Guide for detailed instructions.

Smart Contract

The PaymentRouter contract routes all payments and takes commission:

• Contract: contracts/PaymentRouter.sol
• Deploy: npm run deploy:contract
• Commission: Configurable (default 3%)
• Treasury: Your wallet address

Hosted API Service

For users who prefer managed service:

• Base URL: https://api.irys-x402.com
• Authentication: API key in X-API-Key header
• Pricing: $20/month
• Features: Managed infrastructure, API keys, priority support

See API Documentation for full details.

License

ISC