Skip to content
BranchesTags

Repository files navigation

ORDnet MCP Server v3.3

Enable AI agents to create Web3 content on Bitcoin SV blockchain

Version tests test count tools License

Overview

ORDnet MCP Server enables AI agents (Claude, GPT, etc.) to create permanent, censorship-resistant content on the Bitcoin SV blockchain using the 1SatOrdinals protocol. This is a key component of the freedom of speech infrastructure - allowing AI to autonomously publish Web3 content.

Key Features

  • 45 MCP Tools for complete blockchain content creation, payments and transfers
  • BRC-100 aligned identity (v3.0): ordnet_identity, ordnet_sign_message, ordnet_verify_message, ordnet_derive_payment_address — agent identity, off-chain signing, and per-invoice payment-address derivation as the foundation for x402
  • Agent payments: ordnet_send (P2PKH + optional OP_RETURN reference, miner fee only — x402-ready), ordnet_transfer for ordinals/domains (1SatOrdinals input-0/output-0 semantics, outpoint verified via own node)
  • Binary inscriptions via ordnet_inscribe_binary (base64 → bytes untouched); BSVmap tile claims via ordnet_bsvmap_inscribe
  • Agent conveniences: ordnet_tx_status (confirmations via own node), ordnet_price (via own CoinGecko proxy)
  • 3 MCP Prompts (prompts/list): inscribe-website, register-domain, agent-payment
  • 1SatOrdinals inscriptions (HTML, JSON, text, images, etc.)
  • SNS/OPNS domain registration (.sats, .btc, .bsv, etc.)
  • 3-tier wallet security (env vars → encrypted → plaintext; plaintext-WIF tools are disabled on the HTTP transport)
  • Agent safety layer: tx simulation via ORDnet's own node + spend limits with operator-set hard ceilings (fail-closed)
  • HTTP transport with mandatory bearer auth (ORDNET_MCP_AUTH_TOKEN, server refuses to start without it)
  • Agent-tier service fee: 396 satoshis across 11 outputs to 10 addresses, plus a miner fee of 0.15 sat/byte (min. 200 sats). That is deliberately one tenth of the 3.996-satoshi fee the ORDnet wallets charge — an agent inscribes far more often than a person does, so the per-transaction fee is scaled down to match. The same agent tier applies to ORDmail. See Service fees for the exact split.

Quick Start

Installation

git clone https://github.com/ORDNET/ORDnet-MCP-Server.git && cd ORDnet-MCP-Server
npm install && npm run build

Note: the package is not (yet) published on npm; install from source.

Usage with Claude Desktop

Add to your Claude Desktop config (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ordnet": {
      "command": "node",
      "args": ["/absolute/path/to/ORDnet-MCP-Server/dist/index.js"],
      "env": {
        "ORDNET_WIF": "your-wif-private-key"
      }
    }
  }
}

Usage with OpenClaw

{
  "mcp_servers": [
    {
      "name": "ordnet",
      "command": "node",
      "args": ["/path/to/ordnet-mcp-server/dist/index.js"],
      "env": {
        "ORDNET_WIF": "your-wif-private-key"
      }
    }
  ]
}

Service Fees

Every inscription includes a total service fee of 396 satoshis, split across 11 outputs to 10 addresses (monitor and founder share one), exactly as defined in src/constants.ts (SERVICE_FEE_OUTPUTS). These are the values the code actually writes:

Label Amount Address
ordiBuilder 11 sats 1HdbyucjYU2yfDFXzAQt3kCdP3VvM4tjzr
onnoBuilder 11 sats 1JKcD1kx8XeJFfd32sug1MaXfruurHTCjv
algoBuilder 11 sats 1AHEUcWuCfdRnfwNsvwZhZSetXjEuAvBot
colleagueI 11 sats 1ENW3XBoAv4KQ4FuQ4MtzNkLq82eJd12PV
protocol 22 sats 15q8YQSqUa9uTh6gh4AVixxq29xkpBBP9z
colleagueD 22 sats 1GeifRjPLWTDqL1DZ2vaqorX6pqCi9PyJB
monitor 33 sats 1EXupec98g8TDTG5cwJwH3U8V3PezvvLv8
indexer 44 sats 18RHRqQhsKKZwMnGevvnRQ8KrryAXvQUWQ
partner 66 sats 19o4rByWRvdq6zziJEfhpe4xdq5z43jYrr
founder 77 sats 1EXupec98g8TDTG5cwJwH3U8V3PezvvLv8
foundation 88 sats 1ATEXPH6FSctbZdAz8MnXCfDpCvDnFrWma
Total 396 sats 11 outputs

Miner fee is separate: 0.15 sat/byte, minimum 200 sats.

Why 396 and not 3.996

The ORDnet wallets (Chrome extension, iOS, Android) charge 3.996 satoshis over the same 11-output structure — every amount is exactly ten times the one above. That is not a discrepancy between products: agents and mail run on a deliberately reduced agent tier, because an autonomous agent inscribes far more often than a person opening a wallet. The split across recipients is identical; only the scale differs.

Tier Products Total per inscription
Wallet Chrome extension, iOS, Android 3.996 sats
Agent this MCP server, ORDmail 396 sats

Note: ordnet_send (plain payments / x402 micropayments) carries no service fee — only the miner fee — so agent-to-agent payments stay lean. The x402 facilitator has no service-fee outputs at all.

Tools Reference

Wallet Management (6 tools)

Tool Description
ordnet_wallet_init Initialize wallet from WIF private key †
ordnet_wallet_init_env Initialize from environment variable (recommended)
ordnet_wallet_status Check wallet status and balance
ordnet_wallet_balance Get balance for any BSV address
ordnet_wallet_utxos Get unspent transaction outputs
ordnet_wallet_clear Clear wallet from memory

Inscriptions (6 tools)

Tool Description
ordnet_fee_estimate Calculate fee for an inscription
ordnet_inscribe_prepare Prepare inscription (no broadcast)
ordnet_inscribe_broadcast Broadcast prepared transaction
ordnet_inscribe_html Quick HTML inscription
ordnet_inscribe_json Quick JSON inscription
ordnet_inscribe_text Quick plain text inscription

Domains (6 tools)

Tool Description
ordnet_domain_check Check domain availability
ordnet_domain_info Get domain information
ordnet_domain_search Search registered domains
ordnet_domain_register Register SNS/OPNS domain
ordnet_domain_register_sns Quick SNS registration
ordnet_domain_register_opns Quick OPNS registration

Search & Lookup (4 tools)

Tool Description
ordnet_search_inscriptions Search inscriptions
ordnet_get_inscription Get inscription details
ordnet_get_content_url Get content URLs
ordnet_validate_address Validate BSV address

Security (4 tools)

Tool Description
ordnet_security_encrypt_wallet Encrypt WIF with AES-256-GCM
ordnet_security_tier Check security tier
ordnet_security_validate_password Validate password strength
ordnet_generate_wallet Generate new random wallet †

Payments (5 tools)

Tool Description
ordnet_send Plain BSV payment (miner fee only, no service fee)
ordnet_transfer Transfer an ordinal/domain to another address
ordnet_x402_quote Probe an x402-paywalled URL and parse the quote (SSRF-guarded)
ordnet_x402_fetch Pay an x402 resource in native sats and retrieve it
ordnet_derive_payment_address Derive a BRC-42 payment address (watch-only)

Identity & signing (3 tools)

Tool Description
ordnet_identity Get the wallet's identity public key
ordnet_sign_message Sign a message with the wallet key
ordnet_verify_message Verify a signed message

Utilities (11 tools)

Tool Description
ordnet_info Server information
ordnet_content_types List supported content types
ordnet_tx_simulate Decode/simulate a raw tx via ORDnet's own node
ordnet_policy_set Set spend-policy limits (within operator ceilings)
ordnet_policy_status Show the active spend policy and session total
ordnet_index_health UTXO index health
ordnet_address_watch Add an address to the watch index
ordnet_bsvmap_inscribe Inscribe a BSVmap tile
ordnet_inscribe_binary Inscribe binary content (e.g. an image)
ordnet_tx_status Look up a transaction's status
ordnet_price BSV price in fiat

Total: 45 tools.

† Disabled on the remote HTTP transport: these two tools would move a plaintext private key (WIF) over the network. Locally (stdio) they work; remotely the server refuses them with an explanatory error. Use ordnet_wallet_init_env on servers.

Example: Create an HTML Inscription

User: Create a simple webpage saying "Hello from AI" and inscribe it on Bitcoin

AI: I'll create and inscribe this HTML content on the BSV blockchain.

1. First, let me initialize the wallet...
   [ordnet_wallet_init_env]
   ✓ Wallet initialized at 1ABC...

2. Creating the HTML inscription...
   [ordnet_inscribe_html] content="<html><body><h1>Hello from AI</h1></body></html>"
   
   ✓ Inscription successful!
   - TXID: abc123...
   - Inscription ID: abc123..._0
   - View: https://ordnet.io/view/abc123..._0

Supported Content Types

  • text/html;charset=utf8 - HTML web pages
  • text/plain;charset=utf8 - Plain text
  • application/json - JSON data
  • image/svg+xml - SVG graphics
  • image/png - PNG images
  • image/jpeg - JPEG images
  • image/gif - GIF animations
  • image/webp - WebP images
  • audio/mpeg - MP3 audio
  • video/mp4 - MP4 video
  • application/pdf - PDF documents

Supported Domain Extensions

Universal

  • .sats

Chain-specific

  • BTC: .btc .ord .xbt .gm .unisat .x
  • BSV: .bsv
  • DOGE: .doge .shibe
  • LTC: .ltc
  • BCH: .bch
  • BELLS: .bells
  • And more...

Security Tiers

Tier Method Security Level
Environment ORDNET_WIF env var ⭐⭐⭐ Highest
Encrypted AES-256-GCM encrypted store ⭐⭐ Medium
Plaintext Direct WIF input ⭐ Lowest

Recommendation: Always use environment variables in production.

Development

# Clone and install
git clone https://github.com/ORDNET/ORDnet-MCP-Server.git
cd mcp-server
npm install

# Build
npm run build

# Run the audit regression tests (SSRF guard + spend policy).
# These run straight from source with Node's type stripping:
node --experimental-strip-types test/audit-2026-08-11.test.mjs

# Start server (stdio)
npm start

# Start server (HTTP)
TRANSPORT=http PORT=3000 npm start

Transaction Structure

The inscription transaction follows the same output layout as the reference inscriber (ordmail-v10-standalone-026.html). The service-fee outputs are the 11 entries of SERVICE_FEE_OUTPUTS in src/constants.ts:

Input:   UTXO(s) (user funds)
Output 0:  1 sat    - Inscription (OP_FALSE OP_IF "ord" ... OP_ENDIF + P2PKH)
Output 1:  0 sat    - OP_RETURN "ORDnet.io"
Output 2..12:        - 11 service-fee outputs (11,11,11,11,22,22,33,44,66,77,88 = 396 sats)
Output 13: Change (if > 546 sats)

The exact per-output amounts and addresses are listed under Service Fees above and are the single source of truth (SERVICE_FEE_OUTPUTS). ordnet_send omits the fee outputs entirely.

API Endpoints Used

  • WhatsOnChain: https://api.whatsonchain.com/v1/bsv/main
  • ORDnet Registry: https://registry.ordnet.io
  • ORDnet Search: https://search.ordnet.io

License

MIT © ORDnet.io / Mister HHC B.V.

Links

Environment Variables

Variable Required Purpose
ORDNET_WIF for wallet ops Wallet private key (WIF). On HTTP transport this is the ONLY way to load a wallet.
TRANSPORT no stdio (default) or http.
PORT no HTTP port (default 3000).
ORDNET_MCP_AUTH_TOKEN yes, when TRANSPORT=http Bearer token (min. 32 chars). Server refuses to start without it. Generate: openssl rand -hex 32.
ORDNET_POLICY_MAX_SATS_PER_TX recommended on http Operator hard ceiling per transaction. ordnet_policy_set can tighten below it, never loosen above it.
ORDNET_POLICY_MAX_SATS_PER_SESSION recommended on http Operator hard ceiling per server session.
ORDNET_UTXO_URL no Base URL of the ordnet-utxo index (default http://127.0.0.1:7002).
ORDNET_API no Base URL of the ORDnet API used for price and proxy calls (default https://api.ordnet.io).

Known limitations

  • Wallet and spend-policy state are per server process, not per client session. Run the HTTP transport for a single trusted agent/team behind the auth token, not as a public multi-tenant service.
  • Balance and UTXO lookups use ORDnet's OWN address index (ordnet-utxo, port 7002, every UTXO node-verified) since v2.5; WhatsOnChain is a connectivity fallback only. New tools in v2.5: ordnet_index_health, ordnet_address_watch.
  • UTXO selection skips 1-sat UTXOs as ordinal protection and combines multiple inputs when needed.

About

MCP server that lets AI agents create permanent Web3 content on BSV: 43 tools for inscriptions, .web3 domains, payments and BRC-100 identity.

mcp.ordnet.io

Topics

1sat1satordinalsai-agentai-agentsblockchainbsvbsv-blockchainhermeshermes-agenthermes-skillmcpmcp-serveropenclawopenclaw-skillopenclaw-skillsordinalsordnetweb3

Resources

Readme
MIT license

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages