The Bitcoin SV MCP Server provides a comprehensive suite of tools for interacting with the Bitcoin SV blockchain:
Wallet Operations: Send/receive BSV, manage keys and addresses, create/verify signatures, encrypt/decrypt data, and handle ordinals inscriptions
Blockchain Exploration: Retrieve BSV price, decode transactions, explore chain data (blocks, transactions, addresses) via WhatsOnChain API
NFT & Token Management: Work with Ordinals (NFTs) and BSV-20/21 tokens, get inscription details, search NFTs, access marketplace listings, track sales, and manage MNEE tokens
Data Utilities: Convert between formats (utf8, hex, base64, binary)
Educational Resources: Access information about Bitcoin SV, Ordinals, BSV SDK, and BRC specifications
Customization Options: Run in limited modes (without private key), disable specific tools/prompts, disable transaction broadcasting for testing, and sign ordinal inscriptions with identity keys
Integration: Connect with MCP-compatible clients like Cursor and Claude for Desktop
Provides wallet functionality, BSV blockchain interaction, ordinals/NFT management, and utility tools for Bitcoin SV. Capabilities include retrieving addresses, sending transactions, purchasing NFTs, getting price information, working with ordinals, and managing BSV20 tokens.
Uses Bun as the JavaScript runtime for the MCP server, enabling fast execution of the Bitcoin SV tools and capabilities.
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., "@Bitcoin SV MCP Server check my BSV wallet balance"
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.
BSV MCP connects your AI assistant to Bitcoin SV. Ask it to check a transaction, show your balance, send a payment, or create and trade ordinals (content recorded on the blockchain).
Documentation · All tools · npm · Issues
Install Bun to run the server and Node.js for the npx commands below, then add it to your client:
# Codex
codex mcp add bsv-mcp -- npx -y bsv-mcp@latest --stdio
# Claude Code
claude mcp add --transport stdio bsv-mcp -- npx -y bsv-mcp@latest --stdio
# Grok Build
grok plugin install b-open-io/bsv-mcp --trustChoose one command. For Cursor or Claude Desktop, use this server configuration:
{
"mcpServers": {
"bsv-mcp": {
"command": "npx",
"args": ["-y", "bsv-mcp@latest", "--stdio"]
}
}
}Restart your client, then ask: “Run bsv_status and explain what is available.”
Local stdio needs no Sigma account or OAuth sign-in. It is also the default when
no transport is specified. Existing self-hosted HTTP remains opt-in through
TRANSPORT=http; the deployed hosted endpoint is unchanged.
For the Codex desktop plugin, add b-open-io/claude-plugins in the plugin
marketplace and install BSV MCP. The plugin starts the local npm executable
and requires Node.js and Bun. Claude Code and Grok plugins bundle the local server and
require Bun. Choose one registration to avoid duplicate tools.
Related MCP server: MNEE MCP Server
Ask your assistant to run wallet_onboarding. Create, import or unlock a Vault
in the local browser. Back it up before funding. Enter passwords only in the
local setup UI, never in chat. After a server restart, unlock it again.
To use an existing BRC-100 wallet, configure its signing API instead:
{
"mcpServers": {
"bsv-mcp": {
"command": "npx",
"args": ["-y", "bsv-mcp@latest", "--stdio"],
"env": {
"BRC100_WALLET_URL": "http://127.0.0.1:3321",
"BRC100_WALLET_ORIGINATOR": "bsv-mcp.local"
}
}
}
}The wallet keeps its keys and controls permission requests. Its signing API is separate from a wallet-storage endpoint. See wallet setup for network settings, account selection and project roles.
The package also includes the Bun-based bsv-mcp-local launcher for explicit external,
legacy embedded and project configurations. Source-checkout examples live in
the installation guide.
Protocol revision 2026-07-28 is preferred, with supported 2025 clients
accepted automatically on stdio and HTTP. No compatibility override is needed.
Set MCP_LEGACY_COMPATIBILITY=false only to require modern clients. This
setting also passes through the local launcher. The installed desktop client
was verified using legacy requests; modern support is tested separately.
Modern clients support wallet operations and request-scoped approval. Approval continuations retain the original operation and bind to its authenticated user, arguments, and expiry. Decline, cancellation, or session revocation stops the operation; replaying a continuation does not repeat a transaction. A client without form elicitation cannot approve a spend. External wallets retain their own signer permission flow. The hosted route exposes public reads only.
For the split SDK v2 client:
const client = new Client(
{ name: "my-app", version: "1" },
{ versionNegotiation: { mode: "auto" }, capabilities: { elicitation: { form: {} } } },
);Register a real human approval handler before using approval-dependent tools. Legacy protocol compatibility is enabled by default; the connected client must support the approval flow needed by the requested tool.
The full tool catalog remains the default and is capability-derived: wallet
mode, enabled modules, account context, and the selected profile determine what
tools/list returns. The checked-in manifest is a synthetic baseline for one
configured server, not a promise of a fixed default count. Set
MCP_TOOL_CATALOG=compact only to opt into bounded read families; compact mode
uses the same underlying handlers. Tool availability still
depends on wallet mode and enabled modules. Its baseline read families are
bsv_read, ordinals_read, wallet_read, and utility, each with a bounded
operation enum; unknown operations are rejected. Eligible sessions also expose
separate mutating wallet_setup and wallet_payments families. See the MCP client
protocol support guide for the per-family
operation bounds, endpoint contracts, MCP Apps compatibility, and validation
status.
Two tools cover social operations in both full and compact catalogs:
bsocial_read: posts, replies, search, likes, friends, channels, messages, videos, and raw action history.
bsocial_publish: posts/replies, reposts, likes/unlikes, follows/unfollows, friend/unfriend records, messages, and video records. Tags and attachments use separate, independently signed outputs.
{"action":{"type":"post","content":"Hello Bitcoin","tags":["bitcoin"]},"preview":true}Preview returns unsigned outputs without using keys or spending. Remove preview to publish through the selected identity wallet's existing permissions. Messages are public unless their content was encrypted beforehand; a recipient context does not encrypt them. Friend records advertise a communication public key from an established key-agreement workflow.
See the social guide for examples and migration from the old tool names. PUBLIC_BMAP_URL is the indexer server root (with /social and /q routes), not a wallet or identity API. Raw follow/unfollow records are event history, not a claim about current relationship state.
External mode connects to an existing BRC-100 signer. The signer keeps the private keys, wallet storage, and permission decisions; BSV MCP receives only the SDK signer interface. Embedded mode uses an encrypted local Vault wallet. The wallet-ready screen displays an interactive cloud of the connected session’s available tools, generated from its live catalog.
When setup is needed, wallet_onboarding opens the private browser flow to
create, import, or unlock it. The selected account's database and storage
configuration remain in use. The launcher's existing-account embedded mode
still supplies BSV_MCP_PASSWORD at runtime.
Project mode opens every explicitly assigned role: payments,
identity-signing, one-sat, and encryption. It requires paired project
selectors and BSV_MCP_PASSWORD at runtime; set VAULT_PATH when the Vault
module does not provide a default path. Bindings pin the selected public key
and support direct keys, BRC-42 children, and BRC-157/Yours profile leaves.
Changing the project binding or expiring its session revokes captured handles.
Derived keys have separate storage; selecting the account's payment root keeps
its existing database and deposit prefix.
BRC-100 tools accept walletRole (payments, identity, ordinals, or
encryption). Method defaults select the matching role, and sign/abort action
continuations retain their originating wallet and authenticated user. An
unassigned role fails rather than borrowing another key. BAP tools use the
identity wallet for publication, rotation, attestations, and profiles without
exporting an xprv. That wallet also funds those transactions and retains BAP
records. Signed BSocial posts and SIGMA inscriptions use the configured identity.
External registrations can use the same project root/ID pair to derive an
isolated permission origin, without a Vault password. Optional
BRC100_WALLET_PUBLIC_KEY pins the signer identity. BRC100_WALLET_ROLES is a
JSON object selecting independent role endpoints and public-key pins; see
external signer configuration. The source launcher
accepts external --project-root /absolute/project --project-id project.example.
It defaults to disabled broadcasting; set DISABLE_BROADCASTING=false in its
runtime environment to enable transaction tools with the signer's approval.
Each mode has its own process environment and should be registered as a separate server when you need to switch between them. Use only the registrations needed by the project.
Embedded wallets can list pending PeerPay payments and receive a selected
payment with wallet_peerPayments. Receiving requires a message ID and
acknowledges the message only after the wallet accepts it. These operations do
not pay MessageBox service fees. External signers and Droplit do not expose this tool. Project sessions require
an assigned payment role.
Use utils_find_skills with a short keyword query to find skills in the bOpen
catalog. It returns up to five descriptions and links to versioned SKILL.md
files. It does not download skill contents or install plugins. In compact mode,
select utils_find_skills from the utility tool.
The static tutorial prompts and BRC/BitCom resource catalog have been retired. Use the skill finder for those references. Changelog, JungleBus documentation, and the dashboard app resource remain available.
Connect a compatible existing wallet with BRC100_WALLET_URL, or use the local
Vault browser setup (wallet_onboarding). BSV_MCP_PASSWORD is only for
headless agents: set it in the process environment for that session, never in
MCP client configuration. PRIVATE_KEY_WIF and IDENTITY_KEY_WIF are
migration sources, not live signing keys; import them into Vault and remove the
plaintext copies. Startup never creates keys. See the wallet setup guide for
the required wallet API and configuration.
The default 1Sat API backend is https://api.1sat.app. New mainnet embedded
accounts use https://wallet.1sat.app for wallet storage by default; testnet
accounts do not select a remote storage provider unless configured. Override
ONESAT_API_URL for API services and REMOTE_STORAGE_URL for wallet storage;
these are separate settings. Available tools depend on wallet mode and enabled
modules.
bun install
bun run dev # Website
bun run build:all # MCP server and dashboard
# Supply BRC100_WALLET_URL in the host environment before this launch.
bun --no-env-file scripts/local-mcp-launcher.ts external # Source-checkout local launch
bun testExperimental software; APIs may change. Keep a wallet backup. If a transaction request times out, check whether it succeeded before sending it again. MIT licensed.
package.json "files" is the tarball. prepack runs bun run build:all.
Publish with bun publish. Compile-time libraries are devDependencies;
consumers get the bundled dist/ files, not a second copy of the source tree.
Decodes and analyzes Bitcoin SV transactions to provide detailed insights. This powerful tool accepts either a transaction ID or raw transaction data and returns comprehensive information including inputs, outputs, fee calculations, script details, and blockchain context. Supports both hex and base64 encoded transactions and automatically fetches additional on-chain data when available.
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses behavioral traits such as supporting hex/base64 encoding, fetching on-chain data, and returning detailed insights, but lacks information on error handling, rate limits, or authentication needs, which are important for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, starting with the core purpose. Every sentence adds value, such as input formats and output details, but it could be slightly more streamlined by avoiding redundant phrases like 'powerful tool'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (1 parameter with nested objects, no output schema, and no annotations), the description is somewhat complete but lacks details on return values, error cases, or performance considerations. It covers input semantics well but falls short in fully compensating for the missing structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the input schema, which has 0% coverage. It explains that 'tx' can be a transaction ID or raw data and clarifies encoding options, effectively compensating for the schema's lack of descriptions. However, it doesn't detail the structure of 'args' or provide examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('decodes and analyzes') and resource ('Bitcoin SV transactions'), distinguishing it from siblings like price checking or ordinal tools. It specifies the comprehensive insights returned, making the function unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by mentioning it accepts transaction IDs or raw data, but does not explicitly state when to use this tool versus alternatives like bsv_explore or other Bitcoin-related tools. No exclusions or clear alternatives are provided, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explore Bitcoin SV blockchain data using the WhatsOnChain API. Access multiple data types:
CHAIN DATA:
chain_info: Network stats, difficulty, and chain work
chain_tips: Current chain tips including heights and states
circulating_supply: Current BSV circulating supply
peer_info: Connected peer statistics
BLOCK DATA:
block_by_hash: Complete block data via hash (requires blockHash parameter)
block_by_height: Complete block data via height (requires blockHeight parameter)
tag_count_by_height: Stats on tag count for a specific block via height (requires blockHeight parameter)
block_headers: Retrieves the last 10 block headers
block_pages: Retrieves pages of transaction IDs for large blocks (requires blockHash and optional pageNumber)
STATS DATA:
block_stats_by_height: Block statistics for a specific height (requires blockHeight parameter)
block_miner_stats: Block mining statistics for a time period (optional days parameter, default 7)
miner_summary_stats: Summary of mining statistics (optional days parameter, default 7)
TRANSACTION DATA:
tx_by_hash: Detailed transaction data (requires txHash parameter)
tx_raw: Raw transaction hex data (requires txHash parameter)
tx_receipt: Transaction receipt (requires txHash parameter)
bulk_tx_details: Bulk transaction details (requires txids parameter as array of transaction hashes)
ADDRESS DATA:
address_history: Transaction history for address (requires address parameter, optional limit)
address_utxos: Unspent outputs for address (requires address parameter)
NETWORK:
health: API health check
Use the appropriate parameters for each endpoint type and specify 'main' or 'test' network.
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description lists endpoint functionalities but lacks critical behavioral details: it doesn't specify whether operations are read-only or mutative, rate limits, authentication requirements, error handling, or response formats. While it mentions 'API health check' and parameter requirements, it fails to provide comprehensive behavioral context needed for safe and effective tool invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with categorized sections (CHAIN DATA, BLOCK DATA, etc.) and bullet points for each endpoint, making it easy to scan. It is appropriately sized for a tool with 19 endpoints, though some redundancy exists (e.g., repeating 'requires X parameter' could be streamlined). Every sentence adds value by clarifying endpoint purposes and parameter mappings, with no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (19 endpoints, no annotations, no output schema, and nested input schema), the description is partially complete. It excels in documenting endpoints and parameter mappings but lacks behavioral details (e.g., read/write nature, rate limits) and output information. Without annotations or output schema, the description should ideally cover more behavioral aspects to fully guide the agent, leaving gaps in operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the input schema, which has 0% schema description coverage. It explicitly maps each endpoint to required parameters (e.g., 'block_by_hash: Complete block data via hash (requires blockHash parameter)'), provides optional parameters with defaults (e.g., 'days parameter, default 7'), and clarifies parameter usage across endpoints. This compensates fully for the schema's lack of descriptions, making parameter semantics clear and actionable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Explore Bitcoin SV blockchain data using the WhatsOnChain API. Access multiple data types:' followed by a comprehensive categorization of endpoints (CHAIN DATA, BLOCK DATA, etc.). It specifies the verb 'explore' and resource 'Bitcoin SV blockchain data', distinguishing it from sibling tools like bsv_decodeTransaction (decodes transactions) or bsv_getPrice (gets price data).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: for exploring Bitcoin SV blockchain data via the WhatsOnChain API, with a list of specific endpoint types. It explicitly states 'Use the appropriate parameters for each endpoint type and specify 'main' or 'test' network.' However, it does not explicitly mention when not to use it or name alternatives among sibling tools (e.g., using bsv_decodeTransaction for transaction decoding instead of this tool's tx_by_hash).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves the current price of Bitcoin SV (BSV) in USD from a reliable exchange API. This tool provides real-time market data that can be used for calculating transaction values, monitoring market conditions, or converting between BSV and fiat currencies.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | No parameters required - simply returns the current BSV price in USD |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the tool fetches 'real-time market data' and mentions the source ('reliable exchange API'), which adds useful context. However, it doesn't mention potential limitations like rate limits, authentication requirements, error conditions, or data freshness guarantees that would be important for a price API tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured with two sentences: the first states the core functionality, and the second provides usage context. Every sentence adds value without redundancy, and it's appropriately front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple price retrieval tool with no annotations and no output schema, the description provides adequate purpose and usage context. However, it lacks details about the return format (e.g., numeric value, timestamp, currency pair), error handling, or data source specifics that would be helpful given the absence of structured output documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100% and clearly states 'No parameters required - simply returns the current BSV price in USD'. The description reinforces this by not mentioning any parameters, which is appropriate for a zero-parameter tool. The baseline for 0 parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Retrieves'), resource ('current price of Bitcoin SV (BSV) in USD'), and data source ('from a reliable exchange API'). It distinguishes itself from siblings by focusing on real-time price data rather than transaction decoding, exploration, or ordinal-related functions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('calculating transaction values, monitoring market conditions, or converting between BSV and fiat currencies'). However, it doesn't explicitly state when not to use it or name specific alternatives among the sibling tools for similar price data needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves detailed information about a specific ordinal inscription by its outpoint. Returns complete inscription data including content type, file information, inscription origin, and current status. Useful for verifying NFT authenticity or retrieving metadata about digital artifacts.
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the return data ('complete inscription data including content type, file information, inscription origin, and current status'), which is helpful. However, it lacks details on error handling, rate limits, authentication needs, or performance characteristics, leaving gaps for a mutation-free but data-rich tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by return details and usage context in two efficient sentences. Every sentence adds value without redundancy, making it appropriately sized and well-structured for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (data retrieval with detailed output), no annotations, and no output schema, the description is moderately complete. It outlines the purpose and return data but lacks specifics on output structure, error cases, or operational constraints, which are important for a tool with rich data returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning by specifying the parameter as 'outpoint' and implying its critical role in identifying the inscription, though it does not detail the format beyond what the schema provides ('Outpoint in format 'txid_vout''). For a single parameter tool, this provides adequate context, but not exhaustive detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('retrieves detailed information') and resource ('about a specific ordinal inscription by its outpoint'), distinguishing it from siblings like ordinals_searchInscriptions (searching) or ordinals_getTokenByIdOrTicker (tokens). It provides a precise verb+resource combination that leaves no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('useful for verifying NFT authenticity or retrieving metadata about digital artifacts'), providing clear context. However, it does not specify when NOT to use it or name alternatives (e.g., ordinals_searchInscriptions for broader searches), which prevents a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves detailed information about a specific BSV-20 token by its ID or ticker symbol. Returns complete token data including ticker symbol, supply information, decimals, and current status. This tool is useful for verifying token authenticity or checking supply metrics.
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the tool retrieves detailed information and returns complete token data, which implies a read-only operation, but doesn't explicitly state whether it's safe, requires authentication, has rate limits, or what happens on errors. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with two sentences: the first states the purpose and parameters, and the second provides usage context. It's front-loaded with the core functionality, and every sentence adds value without redundancy. However, it could be slightly more structured by explicitly listing return fields or constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (1 parameter with nested objects, no output schema, no annotations), the description is moderately complete. It covers the purpose, parameters, and usage context but lacks details on return values, error handling, or behavioral traits. Without an output schema, it should ideally explain what 'complete token data' includes, but it doesn't. It's adequate for basic use but has clear gaps for full agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning by specifying that the tool retrieves information 'by its ID or ticker symbol,' which aligns with the two properties in the input schema (id and tick). However, with 0% schema description coverage, the schema provides no descriptions for these parameters. The description compensates somewhat by indicating what the parameters represent, but it doesn't detail formats (e.g., ID as outpoint) or usage rules (e.g., exclusive OR). Baseline is 3 as it adds some value but doesn't fully compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: retrieving detailed information about a specific BSV-20 token by ID or ticker symbol. It specifies the resource (BSV-20 token) and action (retrieving detailed information), and distinguishes it from siblings like ordinals_getInscription or ordinals_marketListings by focusing on token data rather than inscriptions or market listings. However, it doesn't explicitly differentiate from all siblings (e.g., bsv_explore might also retrieve data).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by stating it's 'useful for verifying token authenticity or checking supply metrics,' which suggests when to use it. However, it doesn't provide explicit guidance on when to use this tool versus alternatives like bsv_explore or ordinals_searchInscriptions, nor does it specify prerequisites or exclusions. The guidance is present but not comprehensive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves current marketplace listings for Bitcoin SV ordinals with flexible filtering. Supports multiple asset types (NFTs, BSV-20 tokens, BSV-21 tokens) through a unified interface. Results include listing prices, details about the assets, and seller information.
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that the tool 'retrieves' listings and includes details like prices and seller info, but fails to describe critical behaviors such as pagination handling (implied by 'offset' and 'limit' parameters), rate limits, authentication requirements, error conditions, or the structure of returned results. For a tool with 14 parameters and no output schema, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized at three sentences, front-loaded with the core purpose. Each sentence adds value: the first states the action and scope, the second details asset types, and the third specifies result contents. There's no redundant information, and it's structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (14 parameters, nested objects, no annotations, no output schema), the description is incomplete. It covers the purpose and result types but lacks essential context such as behavioral traits (e.g., pagination, errors), detailed parameter guidance, and differentiation from siblings. Without an output schema, the description should ideally explain return values, but it only mentions them superficially ('listing prices, details about the assets, and seller information').
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning all 14 parameters lack descriptions in the schema. The description compensates partially by mentioning 'flexible filtering' and listing the types of results included (prices, asset details, seller information), which hints at parameters like 'minPrice', 'maxPrice', and 'tokenType'. However, it doesn't explain the semantics of most parameters (e.g., 'id', 'origin', 'pending'), leaving many undocumented. Baseline is 3 due to some compensation but incomplete coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Retrieves current marketplace listings for Bitcoin SV ordinals with flexible filtering.' It specifies the resource (marketplace listings) and the action (retrieves), and mentions support for multiple asset types. However, it doesn't explicitly differentiate from sibling tools like 'ordinals_marketSales' or 'ordinals_searchInscriptions', which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It mentions 'flexible filtering' but doesn't specify scenarios where this tool is preferred over siblings like 'ordinals_marketSales' (which might retrieve sales history) or 'ordinals_searchInscriptions' (which might search inscriptions without marketplace context). No explicit when/when-not instructions or named alternatives are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves recent sales data for BSV-20 and BSV-21 tokens on the ordinals marketplace. This tool provides insights into market activity, including sale prices, transaction details, and token information. Supports filtering by token ID, ticker symbol, or seller address to help analyze market trends and track specific token sales.
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the tool 'retrieves recent sales data' and 'provides insights into market activity,' which implies a read-only operation, but doesn't explicitly state this is a query tool with no side effects. It also doesn't disclose rate limits, authentication requirements, data freshness, or pagination behavior (though pagination parameters exist in the schema). The description adds some behavioral context about what data is returned but leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with three sentences that each add value: first states core purpose, second explains what insights are provided, third describes filtering capabilities and use cases. It's front-loaded with the main purpose and avoids unnecessary repetition. Some minor wordiness exists ('to help analyze market trends and track specific token sales' could be tighter).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (8 parameters in a nested structure, no output schema, no annotations), the description provides basic purpose and filtering context but is incomplete. It doesn't explain the return format, pagination behavior, default tokenType, or what 'recent' means temporally. For a sales data retrieval tool with rich filtering options, more contextual information would be helpful despite the lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions filtering 'by token ID, ticker symbol, or seller address' which maps to three of the eight parameters (id, tick, address). However, with 0% schema description coverage, the description doesn't compensate for the undocumented parameters (dir, limit, offset, pending, tokenType). The description adds some semantic value for three parameters but leaves five completely undocumented beyond the schema structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'retrieves recent sales data for BSV-20 and BSV-21 tokens on the ordinals marketplace' with specific verbs ('retrieves', 'provides insights') and resources ('sales data', 'BSV-20 and BSV-21 tokens'). It distinguishes from siblings like ordinals_marketListings (which likely shows current listings rather than completed sales) and ordinals_getTokenByIdOrTicker (which retrieves token metadata rather than sales data), though the differentiation could be more explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by stating it 'helps analyze market trends and track specific token sales' and mentions filtering capabilities, but doesn't explicitly state when to use this tool versus alternatives like ordinals_marketListings or bsv_getPrice. It provides some guidance through the filtering mention but lacks explicit when/when-not instructions or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches for Bitcoin SV ordinal inscriptions using flexible criteria. This powerful search tool supports filtering by address, inscription content, MIME type, MAP fields, and other parameters. Results include detailed information about each matched inscription. Ideal for discovering NFTs and exploring the ordinals ecosystem.
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral disclosure. It mentions 'results include detailed information' but doesn't specify what that includes, format, or any limitations. No information about rate limits, authentication needs, error conditions, or pagination behavior beyond what's implied in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with zero waste - first states purpose, second enumerates capabilities, third provides usage context. Well-structured and appropriately sized for a search tool with multiple parameters. Could be slightly more front-loaded with explicit sibling differentiation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex search tool with 9 nested parameters, 0% schema coverage, no annotations, and no output schema, the description is inadequate. It doesn't explain return format, error handling, performance characteristics, or provide examples. The 'detailed information' claim is too vague for an agent to understand what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by listing supported filter criteria: 'address, inscription content, MIME type, MAP fields, and other parameters.' This provides meaningful context about what the args object contains, though it doesn't explain individual parameter purposes or relationships. The description adds value beyond the bare schema but doesn't fully document all 9 nested parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'searches for Bitcoin SV ordinal inscriptions using flexible criteria' with specific verb+resource. It distinguishes from siblings like ordinals_getInscription (specific retrieval) and ordinals_marketListings (market-focused), though not explicitly named. However, it doesn't fully differentiate from potential general search tools like bsv_explore.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context ('ideal for discovering NFTs and exploring the ordinals ecosystem') but doesn't explicitly state when to use this tool versus alternatives. It mentions 'powerful search tool' but provides no guidance on when to choose it over other search or retrieval tools in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Converts data between different encodings (utf8, hex, base64, binary). Useful for transforming data formats when working with blockchain data, encryption, or file processing.
Parameters:
data (required): The string to convert
from (required): Source encoding format (utf8, hex, base64, or binary)
to (required): Target encoding format (utf8, hex, base64, or binary)
Example usage:
UTF-8 to hex: {"data": "hello world", "from": "utf8", "to": "hex"} → 68656c6c6f20776f726c64
UTF-8 to base64: {"data": "Hello World", "from": "utf8", "to": "base64"} → SGVsbG8gV29ybGQ=
base64 to UTF-8: {"data": "SGVsbG8gV29ybGQ=", "from": "base64", "to": "utf8"} → Hello World
hex to base64: {"data": "68656c6c6f20776f726c64", "from": "hex", "to": "base64"} → aGVsbG8gd29ybGQ=
Notes:
All parameters are required
The tool returns the converted data as a string
For binary conversion, data is represented as an array of byte values
| Name | Required | Description | Default |
|---|---|---|---|
| args | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: all parameters are required, returns converted data as a string, and explains binary representation. It doesn't mention error handling, performance characteristics, or side effects, but covers essential operational details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and appropriately sized. It starts with a clear purpose statement, provides usage context, documents parameters with examples, and adds important notes. Every sentence adds value, and the information is front-loaded with the most important details first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a data conversion tool with no annotations and no output schema, the description does an excellent job covering purpose, parameters, and basic behavior. The examples are particularly helpful. It could be more complete by mentioning error cases or performance considerations, but it provides sufficient context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0% (no parameter descriptions in schema), so the description fully compensates. It clearly documents all three parameters, their required status, valid values for 'from' and 'to' (utf8, hex, base64, binary), and provides multiple examples showing exactly how to use them together.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Converts') and resource ('data between different encodings'), and distinguishes it from sibling tools by focusing on data format transformation rather than blockchain or ordinal operations. The examples further clarify the exact functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use the tool ('useful for transforming data formats when working with blockchain data, encryption, or file processing'), but doesn't explicitly state when NOT to use it or name specific alternatives among sibling tools. The guidance is helpful but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0bsv_decodeTransactionbsv_explorebsv_getPriceordinals_getInscriptionordinals_getTokenByIdOrTickerordinals_marketListingsordinals_marketSalesordinals_searchInscriptionsutils_convertDataScored across 9 tools
The tools have clear domains (BSV blockchain, ordinals, utilities), but within the bsv_explore tool, many sub-endpoints (e.g., block_by_hash, address_history) are bundled under one tool, which could cause confusion as they represent distinct operations. Other tools like ordinals_getInscription and ordinals_searchInscriptions have overlapping purposes but are differentiated by specific vs. search functionality.
Most tools follow a consistent prefix_snake_case pattern (e.g., bsv_decodeTransaction, ordinals_getInscription, utils_convertData), with clear domain prefixes. However, bsv_explore is an outlier as it groups multiple operations under one name, deviating from the single-action-per-tool convention seen elsewhere.
With 9 tools, the count is reasonable for covering Bitcoin SV blockchain, ordinals, and utilities. However, the bsv_explore tool effectively bundles many sub-operations, making the actual functionality count higher than 9, which could be seen as slightly heavy but still manageable.
The toolset covers key areas: transaction decoding, blockchain exploration, price data, ordinals (inscriptions, tokens, marketplace), and data conversion. Minor gaps include lack of tools for creating or broadcasting transactions, and deeper wallet or smart contract operations, but core read-only and analysis functions are well-represented for the domain.
OpenAI-compatible LLM MCP (7 tools); chat via balance key or x402 USDC on Base
Production-grade MCP gateway delivering 8 real-time AI tools with instant x402 micropayments settled in USDC on Base Mainnet or SPL-USDC on Solana. Features Basescan contract auditing, wallet analytics, headless browser scraping, and pre-scraped oracle data feeds.
Production-grade MCP gateway delivering 8 real-time AI tools with instant x402 micropayments settled in USDC on Base Mainnet or SPL-USDC on Solana. Features Basescan contract auditing, wallet analytics, headless browser scraping, and pre-scraped oracle data feeds.
Bitcoin and YouTube video intelligence for AI agents. Pay-per-call via x402 USDC on Base.
