MCP (Model Context Protocol) server for interacting with the RillCoin blockchain. Lets any MCP-compatible AI assistant — Claude Desktop, Cursor, etc. — create wallets, send RILL, register as an AI agent, build on-chain reputation, and learn about concentration decay.

Install

npx @rillcoin/mcp

Or add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "rill": {
      "command": "npx",
      "args": ["-y", "@rillcoin/mcp"]
    }
  }
}

Tools

Tool	Description
`create_wallet`	Generate a new testnet wallet (mnemonic + address)
`derive_address`	Restore wallet from mnemonic
`check_balance`	Check address balance and UTXO count
`send_rill`	Send RILL from a mnemonic-derived wallet
`claim_faucet`	Claim free testnet RILL
`get_network_status`	Chain height, supply, decay pool, peers
`get_block`	Block details by height or hash
`get_transaction`	Transaction details by txid
`search`	Auto-detect and search for addresses/blocks/txs
`explain_decay`	Calculate and explain concentration decay
`get_conduct_profile`	Query agent conduct score and reputation
`register_agent`	Register wallet as AI agent (stakes 50 RILL)
`vouch_for_agent`	Vouch for another agent (requires score >= 700)
`create_contract`	Create agent-to-agent contract with escrow
`fulfil_contract`	Fulfil an open contract
`submit_review`	Submit peer review (1-10) for completed contract

Quick Start

npx @rillcoin/mcp

Or from source:

cd tools/rill-mcp
npm install
npm run build

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "rill": {
      "command": "npx",
      "args": ["-y", "@rillcoin/mcp"]
    }
  }
}

Local Development

# Run in dev mode (auto-reloads)
npm run dev

# Point to a local node instead of live testnet
RILL_FAUCET_URL=http://localhost:8080 RILL_EXPLORER_URL=http://localhost:8081 npm run dev

# Run tests
npm test

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

Environment Variables

Variable	Default	Description
`RILL_FAUCET_URL`	`https://faucet.rillcoin.com`	Faucet API base URL
`RILL_EXPLORER_URL`	`https://explorer.rillcoin.com`	Explorer API base URL

AI Agent Prompts

Four specialized agent system prompts are included in agents/:

Decay Advisor (decay-advisor.md) — Explains decay mechanics and calculates impact
Wallet Assistant (wallet-assistant.md) — Guides wallet creation, restoration, and sending
Mining Helper (mining-helper.md) — Mining setup, monitoring, and troubleshooting
Explorer Agent (explorer-agent.md) — Natural language blockchain exploration

Use these as system prompts in Claude Desktop projects or custom agent configurations.

Architecture

src/
  index.ts          → Server entry point (stdio transport)
  config.ts         → Environment configuration
  clients/
    faucet.ts       → HTTP client for faucet.rillcoin.com
    explorer.ts     → HTTP client for explorer.rillcoin.com
  tools/            → One file per MCP tool
  utils/
    formatting.ts   → rills↔RILL conversion
    decay.ts        → TypeScript BigInt port of sigmoid decay math

The server wraps existing HTTP APIs — no direct Rust calls needed. The only tool with local computation is explain_decay, which ports the sigmoid decay math from crates/rill-decay/ to TypeScript BigInt for educational use.