Blockia MCP Server

Blockia MCP Server exposes Blockia Pay payment capabilities to Model Context Protocol (MCP) compatible clients such as Claude Desktop.

Features

• get_balance – return the agent wallet balance on the configured wallet and network.
• process_payment_link - fetch the payment link details and execute the payment.
• fetch_with_payment – call premium API endpoints that support X402 payment challenges (e.g. /api/premium-data); the tool handles the payment negotiation and returns the final response payload.

All tool handlers use the @blockia-pay/blockia-agent-sdk so they stay in sync with the Agentic SDK.

Prerequisites

• MCP compatible client
• Wallet

Installation & Build

pnpm install
pnpm --filter @blockia-pay/blockia-mcp-server build

Environment Variables

| Variable | Required | Description | | ------------- | -------- | ------------------------------------------------------------------------ | | PRIVATE_KEY | ✅ | Private key used to authenticate and connect agent operations to wallet. |

Running (STDIO)

The server currently supports STDIO transport only. It is designed to be spawned by an MCP-compatible client.

Example Claude Desktop Configuration

Add the following entry to '~/Library/Application Support/Claude/claude_desktop_config.json' (create the file if it does not exist):

{
  "mcpServers": {
    "blockia-pay": {
      "command": "npx",
      "args": ["-y", "@blockia-pay/blockia-mcp-server"],
      "env": {
        "PRIVATE_KEY": "your-actual-private-key"
      }
    }
  }
}

Example Flow

1. Claude calls get_balance → Returns the current wallet balance.
2. Claude calls process_payment_link with the full payment link URL (e.g., http://localhost:4000/x402/XunAs3BV8a5hJvWHKgBXTrPr8KwsaZnq) →
   • The server extracts the payment link ID from the URL,
   • Fetches the payment request details,
   • Executes the payment,
   • Returns a confirmation with payment requirements and transaction result.

Premium Endpoint Flow

1. Claude calls get_balance → Returns the current wallet balance (recommended but optional if you already know the balance).
2. Claude calls fetch_with_payment with the full premium endpoint URL (e.g., http://localhost:4000/api/premium-data) →
   • The server forwards the URL to the Agent SDK,
   • Handles the X402 payment challenge automatically (selecting a suitable requirement, signing the payload, retrying with X-PAYMENT headers),
   • Returns the final HTTP status, headers, and body for the requested resource.

This demonstrates how Claude (or any MCP-compatible agent) can interact with Blockia Pay through MCP tools.