Radiant MCP Server

Model Context Protocol (MCP) server for the Radiant blockchain — lets AI agents query chain state, manage Glyph tokens, resolve WAVE names, and — when given a private key — build, sign, and broadcast transactions on the Radiant network.

## ⚠️ This server can hold private keys and move funds

>

Unlike a read-only data server, radiant-mcp-server exposes a full write/signing surface. It can:

>

- Store WIF private keys server-side in a keyring at ~/.radiant-mcp/keyring.json (override with RADIANT_KEYRING_FILE). The file is required to be 0600 (owner read/write only) on POSIX — the server refuses to load it otherwise. - Generate and restore wallets — random keys and BIP39 mnemonics — returning WIF private keys and seed phrases in tool output. - Build, sign, and broadcast transactions — send RXD, batch-pay, and mint / transfer / burn Glyph tokens — using either a transient WIF passed per call or a key referenced by alias from the keyring.

>

Any agent or client connected to this server can invoke those tools. Treat connecting it like handing over a hot wallet. Read Security & key handling before exposing it beyond loopback.

Features

59 tools across 12 categories

Read/query tools need no keys. The Keyring, Wallet, and Transactions categories hold or receive private keys and can move funds — see Security & key handling.

#### Read & query — no private keys

Blockchain (8 tools)

• radiant_get_chain_info — Current chain status (height, tip hash, network params)
• radiant_get_balance — RXD balance for an address (confirmed + unconfirmed)
• radiant_get_utxos — List unspent outputs for an address
• radiant_get_history — Full transaction history for an address (returns all entries — large for active addresses)
• radiant_get_transaction — Transaction details by txid
• radiant_get_block_header — Block header by height
• radiant_estimate_fee — Fee estimate (ElectrumX estimate + min-relay policy floor)
• radiant_broadcast_transaction — Broadcast a pre-signed raw tx (no key required, but publishes to the network)

Glyph Tokens (10 tools)

• radiant_get_token — Token info by reference
• radiant_list_tokens — Tokens held by an address
• radiant_get_token_balance — Specific token balance for an address
• radiant_search_tokens — Search tokens by name/ticker
• radiant_get_token_metadata — Full CBOR metadata
• radiant_get_token_history — Token transaction history
• radiant_get_tokens_by_type — Filter tokens by type (FT/NFT/etc.)
• radiant_validate_protocols — Check whether a Glyph protocol combination is valid
• radiant_parse_glyph_envelope — Decode a Glyph envelope from raw script hex
• radiant_get_token_utxos — Discover all token UTXOs (and their tokenRefs) held by an address

dMint Mining (4 tools)

• radiant_get_dmint_contracts — List active mineable tokens
• radiant_get_dmint_contract — Details for one dMint contract
• radiant_get_dmint_by_algorithm — dMint contracts filtered by mining algorithm
• radiant_get_most_profitable_dmint — dMint contracts ranked by profitability

WAVE Naming (5 tools)

• radiant_resolve_wave_name — Resolve a WAVE name to its zone records
• radiant_check_wave_available — Check name availability
• radiant_wave_reverse_lookup — Names owned by an address
• radiant_wave_subdomains — List child names of a WAVE name
• radiant_wave_stats — Naming-system statistics

DEX / Swap (2 tools)

• radiant_get_swap_orders — Open swap orders for a pair (on-chain orderbook)
• radiant_get_swap_history — Trade history for a token

Connection & Monitoring (3 tools)

• radiant_connection_health — ElectrumX connection status and latency
• radiant_reconnect — Force a fresh ElectrumX reconnect when the session is wedged
• radiant_watch_address — Subscribe to real-time payment notifications for an address (ElectrumX scripthash subscription)

Utility / Reference (2 tools)

• radiant_get_protocol_info — Glyph protocol type reference
• radiant_validate_address — Validate an address; show its type (P2PKH/P2SH) and scripthash

Script Tools — offline (2 tools)

• radiant_decode_script — Decode raw script hex into human-readable opcodes (no network)
• radiant_compile_script — Compile RadiantScript (.cash/.rxd) source into a deployment artifact (ABI, ASM, hex). Offline; requires the rxdc compiler binary (set RXDC_PATH, or keep the RadiantScript repo as a sibling directory)

On-Chain AI Primitives (9 tools)

• radiant_create_inference_proof — blake3 inference-proof commitment hash(modelHash ‖ inputHash ‖ output)
• radiant_verify_inference_proof — Verify an inference-proof commitment off-chain
• radiant_build_agent_profile — Build an AI-agent identity profile (+ WAVE zone records) with a blake3 commitment
• radiant_resolve_agent_identity — Resolve an agent's identity (capabilities, pricing, API endpoint) from its WAVE name
• radiant_check_token_access — Token-gated access check (does an address hold the minimum balance?)
• radiant_open_channel — Build initial state for a micropayment channel
• radiant_update_channel — Update channel state (transfer photons payer → payee)
• radiant_build_data_asset — Build Glyph NFT metadata for a data-marketplace asset
• radiant_search_data_assets — Search the data marketplace (datasets, models, etc.)

These AI primitives compute commitments/metadata or read chain state — they do not hold keys or broadcast. Use the Transactions tools below to publish their output on-chain.

#### Write & signing — private keys involved

🔑 The next three categories are the security-relevant surface. See Security & key handling.

Keyring — server-side WIF storage (3 tools)

• radiant_register_key — Store a WIF private key under an alias in the server-side keyring (~/.radiant-mcp/keyring.json, 0600). Lets signing tools reference the key by key_alias instead of resending the WIF on every call
• radiant_list_keys — List registered aliases and their derived addresses (WIFs are never returned)
• radiant_remove_key — Remove an alias from the keyring

Wallet — key generation & derivation (3 tools)

• radiant_create_wallet — Generate a new wallet (random key, or BIP39 mnemonic with BIP32 HD derivation). Returns the WIF and, if requested, the mnemonic
• radiant_restore_wallet — Restore a wallet from a BIP39 mnemonic. Returns the derived WIF
• radiant_derive_address — Derive an address / public key / WIF from a mnemonic + BIP32 path (per-task sub-wallets)

Transactions — build, sign & broadcast (8 tools)

Each accepts either a transient wif (sent through the transport) or a key_alias from the keyring. Unless noted, these sign and broadcast.

• radiant_send_rxd — Send RXD: select coins, build, sign, broadcast 🔑
• radiant_send_batch — Send RXD to up to 100 recipients in one transaction 🔑
• radiant_transfer_token — Transfer a Glyph FT/NFT to another address 🔑
• radiant_burn_token — Permanently burn a Glyph token (Glyph protocol 6) 🔑
• radiant_create_ft — Mint a Glyph Fungible Token (2-tx commit+reveal) 🔑
• radiant_create_nft — Mint a Glyph NFT (2-tx commit+reveal) 🔑
• radiant_build_transaction — Build and sign a transaction in dry-run mode; returns raw hex/fee/size without broadcasting (set dry_run=false to broadcast). Inspect before committing high-value txs 🔑
• radiant_estimate_tx_fee — Estimate fee from input/output counts (pure arithmetic — no key, no network, no broadcast)

10 Resources

Static reference data (6)

• radiant://docs/chain-overview — Blockchain overview
• radiant://docs/opcodes — Opcode reference (including V2)
• radiant://docs/protocols — Glyph protocols, dMint algorithms, DAA modes
• radiant://docs/network-params — Network parameters (JSON)
• radiant://docs/sdk-quickstart — radiantjs quick-start guide
• radiant://docs/knowledge-base — Comprehensive AI knowledge base

Dynamic / live data (4)

• radiant://chain/status — Live chain status (height, tip hash, sync state)
• radiant://dmint/active — Currently active dMint contracts
• radiant://network/fees — Fee estimates for several confirmation targets
• radiant://tokens/popular — Popular fungible tokens and NFT collections

Transports

The same 59 tools and 10 resources are exposed over three transports (all driven by the single source of truth in src/register-tools.ts):

REST API

A standard REST API mirrors the tools for any HTTP client. Key-handling endpoints (/keyring/*, /wallet/*, /tx/*, /token/*) are auth-gated — see Security & key handling.

# Start REST server
npm run start:rest

# Query chain info
curl http://localhost:3080/api/chain

# Get address balance
curl http://localhost:3080/api/address/1A1zP1.../balance

# Search tokens
curl http://localhost:3080/api/tokens/search?q=mytoken

# Full endpoint list
curl http://localhost:3080/api

OpenAPI 3.1 spec: docs/openapi.yaml

Security & key handling

This server has a real write surface. The defaults are loopback-only and conservative, but you should understand them before exposing the server.

How private keys reach the server

1. Transient WIF — pass wif on each signing call. It travels through the MCP/HTTP transport and may appear in agent transcripts and client logs.
2. Server-side keyring — call radiant_register_key once, then reference the key by key_alias on later calls. The WIF stays out of subsequent transport/transcripts but is persisted on disk in the keyring file.

The keyring file

• Location: ~/.radiant-mcp/keyring.json (override with RADIANT_KEYRING_FILE).
• Permissions: must be 0600 (owner read/write only) on POSIX. The server refuses to load a keyring with looser permissions (chmod 600 <path> to fix), and writes new entries back at 0600.
• Contents: WIF private keys in plaintext JSON. Anyone who can read this file controls the funds. radiant_list_keys never returns WIFs, but the file itself does contain them.

Network exposure & auth (REST and SSE)

Both HTTP transports default to loopback (HOST=127.0.0.1) so key-handling tools are not exposed to the LAN by accident.

• REST — key-handling endpoints (/keyring/*, /wallet/create, /wallet/restore, /wallet/derive, /tx/send, /tx/build, /tx/send-batch, /token/create/ft, /token/create/nft, /token/transfer, /token/burn) are wrapped in an auth check:
• RADIANT_API_TOKEN set → those endpoints require Authorization: Bearer <token>.
• RADIANT_API_TOKEN unset → those endpoints are loopback-only (127.0.0.1 / ::1); non-loopback requests get 401.
• This holds even if you set HOST=0.0.0.0 — key endpoints stay locked down until a token is configured. Read-only endpoints are not token-gated, so binding to 0.0.0.0 exposes read queries to the network.
• SSE — binds loopback by default and logs a warning if HOST is non-loopback, because the SSE transport exposes the WIF-handling tools. Put an authenticated reverse proxy in front before allowing remote access.

To expose write endpoints remotely: set RADIANT_API_TOKEN to a strong secret, set HOST=0.0.0.0 (ideally behind a TLS-terminating reverse proxy), and send the bearer token on every key-handling request.

Safety switch

Set RADIANT_TEST_MODE (to any value other than 0/false) to block real broadcasts — radiant_broadcast_transaction and the signing tools will refuse to publish. Useful for dry runs and CI.

Installation

npm install
npm run build

Configuration

Windsurf / Cascade

Add to your MCP settings (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "radiant": {
      "command": "node",
      "args": ["/path/to/radiant-mcp-server/dist/index.js"],
      "env": {
        "ELECTRUMX_HOST": "electrumx.radiantcore.org",
        "RADIANT_NETWORK": "mainnet"
      }
    }
  }
}

⚠️ This launches the full server, including the keyring, wallet, and signing tools. Any key registered via radiant_register_key is written to ~/.radiant-mcp/keyring.json and is usable by the agent on every subsequent call. Only connect it in an environment you trust to act on those funds.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "radiant": {
      "command": "node",
      "args": ["/path/to/radiant-mcp-server/dist/index.js"],
      "env": {
        "ELECTRUMX_HOST": "electrumx.radiantcore.org"
      }
    }
  }
}

Environment Variables

Development

# MCP server (development)
npm run dev

# REST API server (development)
npm run dev:rest

# SSE server (development)
npm run dev:sse

# Type check
npm run lint

# Build
npm run build

# Run tests
npx tsx test/smoke.ts   # MCP smoke test (no network)
npx tsx test/live.ts    # MCP live test (ElectrumX)
npx tsx test/rest.ts    # REST API test (ElectrumX)

Architecture

AI Agent (Windsurf/Claude/Cursor)       Web App / HTTP Client
       │ MCP Protocol (stdio / SSE)            │ HTTP/REST
       ▼                                       ▼
radiant-mcp-server (index.ts / sse.ts)  radiant-rest-api (rest.ts)
  ├── Tools (59)                          ├── REST endpoints
  ├── Resources (10)                      ├── OpenAPI 3.1 spec
  │                                       └── bearer-token / loopback auth
  ├── Keyring (~/.radiant-mcp, 0600) ─────────────┤  (key-handling tools)
  └──────────┬────────────────────────────────────┘
             │ Shared ElectrumX Client (TCP/TLS)
             ▼
      RXinDexer / ElectrumX
        (Glyph + WAVE + Swap + dMint APIs)

All transports register the same tools/resources via src/register-tools.ts.

About Radiant

Radiant (RXD) is a Layer 1 UTXO proof-of-work blockchain with native digital asset support. Key features:

• SHA512/256d mining algorithm
• Glyph token standard (FT, NFT, dMint, WAVE names, 11 protocol types)
• 256 MB blocks, 5 minute block time
• 21 billion max supply
• V2 opcodes (block 410,000+): OP_BLAKE3, OP_K12, OP_LSHIFT, OP_RSHIFT, OP_2MUL, OP_2DIV

License

MIT