@ordinal402/ordinal-mcp
Browse, inspect, try, and pay for Ordinal marketplace services from a local MCP bridge, with local signing and on-chain settlement checks.
List marketplace services and filter by query, category, or maximum price.
Get full details for a service: input/output schema, price, examples, docs, and x402 terms.
Run a service for free without payment or usage recording.
Make paid service calls signed locally by your wallet, with an optional maxPrice spend guard, returning the response and settlement transaction.
Check a Robinhood Chain settlement transaction for success, confirmations, and explorer URL.
Show which wallet will pay and whether a private key is configured.
Use it from Claude Code, Codex, Claude Desktop, Cursor, Windsurf, Gemini CLI, VS Code, or any JSON-RPC stdio client; free tools work without a key.
Settles x402 service payments on Robinhood Chain (chain id 4663) via a locally signed EIP-712/Permit2 authorization, and provides a tool to look up Robinhood Chain transactions by hash to check success, confirmations, and explorer URL.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@ordinal402/ordinal-mcp List the services available for under $5."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@ordinal402/ordinal-mcp
Pay for Ordinal marketplace calls from your own wallet, in Claude Code or Codex.
x402's exact scheme needs an EIP-712 signature from the payer for every
payment, so whatever pays has to hold the key. This bridge runs on your machine
for exactly that reason: browsing is forwarded to Ordinal untouched, and only
the signing happens here. Ordinal receives a signature and recovers your address
from it — never the key.
Install
Nothing to install. Every client below runs it on demand; they differ only in where the configuration lives.
Claude Code
claude mcp add ordinal -e ORDINAL_PRIVATE_KEY=0xYOUR_KEY -- npx -y @ordinal402/ordinal-mcp@latestCodex — add to ~/.codex/config.toml:
[mcp_servers.ordinal]
command = "npx"
args = ["-y", "@ordinal402/ordinal-mcp@latest"]
[mcp_servers.ordinal.env]
ORDINAL_PRIVATE_KEY = "0xYOUR_KEY"Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json
on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows. Quit and
reopen the app afterwards; a window reload is not enough.
{
"mcpServers": {
"ordinal": {
"command": "npx",
"args": ["-y", "@ordinal402/ordinal-mcp@latest"],
"env": { "ORDINAL_PRIVATE_KEY": "0xYOUR_KEY" }
}
}
}Cursor — same shape, in ~/.cursor/mcp.json, or .cursor/mcp.json inside a
repository to scope it to one project. Windsurf reads the same shape from
~/.codeium/windsurf/mcp_config.json, Gemini CLI from ~/.gemini/settings.json.
VS Code — .vscode/mcp.json. The object is named servers, not
mcpServers, and wants an explicit type:
{
"servers": {
"ordinal": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@ordinal402/ordinal-mcp@latest"],
"env": { "ORDINAL_PRIVATE_KEY": "0xYOUR_KEY" }
}
}
}Anything else — it is JSON-RPC 2.0 over stdin and stdout, so any client that can launch a command works:
ORDINAL_PRIVATE_KEY=0xYOUR_KEY npx -y @ordinal402/ordinal-mcp@latestLeave the key out and everything still works except paid calls — browsing and free trials need no wallet at all.
Longer walkthrough, including funding the wallet and what to do when something fails: https://www.ordinal402.xyz/docs#agents.
Related MCP server: mcp-inscription
Before your first paid call
The payer wallet needs, on Robinhood Chain (chain id 4663):
USDG for the service price
a little ETH — only for the one-time approval below
a one-time Permit2 approval of USDG:
cast send 0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168 \
"approve(address,uint256)" \
0x000000000022D473030F116dDEE9F6B43aC78BA3 \
0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff \
--private-key 0xYOUR_KEY --rpc-url <robinhood-rpc>After that every payment is gasless for you — Ordinal's relayer broadcasts and pays the gas. You only ever sign.
Use a plain EOA. Permit2 treats an address that holds code as a smart wallet and
calls isValidSignature on it; if that contract does not implement ERC-1271 the
settlement reverts.
Tools
Tool | Cost | What it does |
| free | Browse the catalogue. Filter by |
| free | Input/output schema, price, x402 terms. Read before calling. |
| free | Runs the provider for real. Settles nothing, records nothing. |
| paid | Signs locally, settles on chain, returns the response and the transaction. |
| free | Look up a settlement transaction. |
| free | Which wallet will pay, and whether a key is configured. |
Configuration
Variable | Default | Meaning |
| — | Payer key, |
|
| Marketplace origin. |
| — | Only if the marketplace endpoint is gated. |
Why this is safe to give a key
Asking for a private key is the largest thing software can ask of you, so this package is small enough to read in full and published in a way you can verify.
The source is here.
src/index.tsis around 200 lines. The key appears in exactly one place: constructing a viem account that signs typed data locally.It is never transmitted. Search the source for the key variable. It is never placed in a request body, a header, a URL, a file, or a log line.
The published package is provenance-signed. npm ties the tarball to the commit in this repository and the GitHub Actions run that built it, so the code you read here is the code you install. Check it on the package page.
It only ever signs. The bridge cannot move funds on its own. Every payment is a signature over a challenge that names the exact amount and recipient, and the marketplace settles that one payment and nothing else.
Nothing is required. Leave the key unset and browsing and free trials still work.
Use a wallet funded with only what you intend to spend. That is good practice with any agent, not a caveat specific to this one.
What is sent where
list_services / get_service_details / try_service
→ forwarded to the marketplace. No key involved.
call_service
→ fetch the 402 challenge from the marketplace
→ sign it HERE, with your key, on this machine
→ send only the signature
→ the marketplace settles it and records the call against your addressYour private key is read from this process's environment and used to sign. It is never written anywhere, never logged, and never sent over the network.
Available Tools
6 toolscall_serviceCall a service with paymentA
Execute a real paid call, settled on Robinhood Chain from this machine's wallet (no key configured yet). The payment is signed locally; the private key never leaves this machine. Returns the provider response plus the settlement transaction.
Inputs: input (required), service (required), maxPrice.
check_payment_statusCheck a settlement transactionA
Look up a Robinhood Chain transaction by hash and report whether it succeeded, how many confirmations it has, and its explorer URL.
Inputs: txHash (required), network.
get_service_detailsGet service detailsA
Full detail for one service: input/output JSON Schema, price, example request and response, documentation, and the x402 settlement terms. Call this before try_service or call_service so the input matches the schema.
Inputs: service (required).
list_servicesList marketplace servicesA
Browse published Ordinal services. Optionally filter by free-text query, category, or a maximum price per call. Returns id, slug, name, description, price, and reliability metrics.
Inputs: limit, query, category, maxPrice.
try_serviceTry a service for freeA
Run a service without paying. Validates the input against the service schema and returns the provider's real response, but settles no payment and records no usage. Use this for demos and for checking output shape before committing to a paid call.
Inputs: input (required), service (required).
wallet_addressShow the paying walletA
Reports which wallet this bridge will pay from, and whether a key is configured at all. Useful before a paid call.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct action: browsing, inspecting, trying, calling, checking payment status, and checking wallet identity. The try_service versus call_service distinction is clearly drawn by payment and settlement semantics.
Five of six tools follow a clear verb_noun snake_case pattern. The sole exception is wallet_address, which is a noun phrase rather than a get_* verb, but it remains readable and predictable.
At six tools, the set is tightly scoped to the service marketplace workflow: discover, inspect, try, pay, verify, and wallet identity. There is no bloat or redundancy.
The core lifecycle from discovery through paid execution to settlement verification is covered. Minor gaps exist: there is no transaction history tool and no way to configure the wallet within the MCP surface, but agents can work around both.
Maintenance
Related MCP Connectors
Pay-per-token Claude & Grok inference, settled in Bitcoin BSV. npm package or hosted remote.
Monetization and execution gateway for autonomous AI agents on Base Mainnet
Non-custodial RFQ and atomic swap settlement for AI agents. Escrow onchain, signed receipts.
Marketplace and payment rail for AI agents: list, buy and settle with signed receipts.
Related MCP Servers
- AlicenseBqualityFmaintenanceConnects a Bitcoin Lightning wallet to your LLM using Nostr Wallet Connect, enabling payment functionalities within language models like Claude.611 npm15MIT
- AlicenseBqualityDmaintenanceEnable AI assistants to interact directly with Bitcoin Ordinals inscriptions. Seamlessly integrates with Goose and Claude Desktop to retrieve and display inscription content from transactions.14MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables gasless blockchain transactions directly from Claude conversations, allowing users to execute transfers, swaps, and other operations without holding native tokens.2MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients such as Claude Desktop and Cursor to obtain Base L2 payment instructions and extract clean, token-estimated Markdown from web pages after on-chain verification of a 0.05 USDC payment.MIT