🤖MCP Server
The Xverse MCP server provides a standardized interface that allows any compatible AI model or agent to access Bitcoin blockchain data through the Xverse API — including Bitcoin transactions, Ordinals, Runes, BRC-20, Spark, and swap quotes.
Connect to the MCP server natively in Claude, Cursor, and other clients, or use the mcp-remote module for backwards compatibility with clients that do not support remote MCP.
The Xverse MCP server is centrally hosted, uses Streamable HTTP transport, and authenticates with your existing Xverse API key. It exposes 54 read-only tools across Bitcoin, Ordinals, Runes, BRC-20, Spark, and Swaps — with more functionality on the way.
Setup Instructions
General
The MCP server supports Streamable HTTP transport and authenticates via your Xverse API key passed as a Bearer token:
https://mcp.secretkeylabs.io/mcpAuthentication: Authorization: Bearer <your-api-key>
You can get an API key from the Get Started page.
Claude Code
claude mcp add --transport http xverse https://mcp.secretkeylabs.io/mcp \
--header "Authorization: Bearer <your-api-key>"Then run /mcp once you've opened a Claude Code session to verify the connection.
Cursor
CTRL/CMD + , to open Cursor settings. Navigate to the MCP tools page and add a new server with the following configuration:
Visual Studio Code
CTRL/CMD + P and search for MCP: Add Server. Select Command (stdio) and enter:
Enter the name Xverse and hit enter. Activate the server using MCP: List Servers, selecting Xverse, and selecting Start Server.
Alternatively, add to your VS Code MCP settings file:
Codex
Run the following command in Terminal:
If this is your first MCP in Codex, enable the rmcp feature first:
Windsurf
CTRL/CMD + , to open Windsurf settings. Scroll to Cascade → MCP servers, select Add Server → Add custom server, and add:
Zed
CMD + , to open Zed settings. Add the following:
Others
Many tools now support MCP servers. Configure them with the following settings:
Command
npx
Arguments
-y mcp-remote https://mcp.secretkeylabs.io/mcp --header "Authorization: Bearer <your-api-key>"
Environment
None
Available Tools
The MCP server exposes 54 read-only tools organized by domain. All tools correspond to endpoints in the Xverse API.
🟠 Bitcoin
bitcoin_get_fee_estimates
Current mempool fee estimates for next blocks
bitcoin_get_mempool_stats
Projected mempool block statistics
bitcoin_get_transaction
Transaction details including inputs, outputs, and confirmations
bitcoin_get_transaction_hex
Raw transaction hex
bitcoin_get_address_balance
Confirmed and unconfirmed balance for an address
bitcoin_get_address_utxos
Mempool-aware UTXOs with inscription filtering
bitcoin_get_address_summary
Address summary with recent transaction IDs
bitcoin_get_address_unconfirmed_txs
Pending mempool transactions for an address
bitcoin_get_price
Current BTC price
🖼️ Ordinals & Collections
ordinals_get_address_utxos
UTXOs containing inscriptions or rare sats
ordinals_get_address_inscriptions
Inscriptions owned by an address
ordinals_get_address_collections
Collections held by an address
ordinals_get_inscription
Single inscription details
ordinals_get_inscription_activity
Inscription transfer history
ordinals_batch_get_inscriptions
Batch inscription lookup (max 25)
ordinals_get_transaction
Inscription-enriched transaction details
ordinals_get_transaction_inputs
Inscription-enriched transaction inputs
ordinals_get_transaction_outputs
Inscription-enriched transaction outputs
ordinals_batch_get_outputs
Batch output details (max 20)
ordinals_list_collections
Browse ordinal collections
ordinals_get_collection
Collection metadata and market info
ordinals_get_collection_holders
Collection holder list
ordinals_get_collection_inscriptions
Inscriptions in a collection
ordinals_get_collection_floor_prices
Historical floor price data
ordinals_top_collections_by_volume
Top collections ranked by trading volume
🔲 Runes
runes_get_address_balances
All Runes balances for an address
runes_get_address_activity
Rune activity for a specific address and rune
runes_get_address_utxos
Mempool-aware Rune UTXOs
runes_get_info
Rune details — supply, symbol, divisibility, market data
runes_get_holders
Top holders for a rune
runes_get_activity
Recent transfer and mint activity
runes_batch_get_info
Batch rune info (max 10)
runes_top_by_volume
Top runes ranked by trading volume
runes_top_gainers_losers
Top gainers and losers by price change
runes_get_floor_prices
Historical floor price data
runes_decode_runestone
Decode runestone data from raw transaction hex
🪙 BRC-20
brc20_get_address_balances
All BRC-20 balances for an address
brc20_get_address_ticker_balance
Balance for a specific BRC-20 token
brc20_get_address_unspent_transfers
Unspent BRC-20 transfer inscriptions
brc20_get_ticker_info
Token details — supply, holders, deploy info
brc20_batch_get_tickers
Batch BRC-20 token info
⚡ Spark
spark_get_token_info
Token info with pool metadata and pricing
spark_get_token_holders
Token holder list
spark_get_token_transactions
Token transaction history
spark_get_token_details
Token details or search by name/ticker
spark_get_address_balances
All BTKN token balances for an address
spark_get_address_transactions
Address transaction history
spark_get_address_summary
Address summary
spark_get_transaction
Transaction details
spark_get_latest_transactions
Latest network transactions
spark_get_token_rankings
Top tokens by volume and TVL
spark_batch_get_token_metadata
Batch token metadata (max 100)
🔄 Swaps
swaps_get_destination_tokens
Available destination tokens for a swap
swaps_get_quotes
Aggregated swap quotes from multiple AMMs (read-only)
FAQ
What authentication does the MCP server use?
The MCP server uses your Xverse API key as a Bearer token. Pass it in the Authorization header on connection. The same API key you use for REST API calls works with the MCP server — no separate credentials needed.
Does the MCP support Streamable HTTP?
Yes, at the https://mcp.secretkeylabs.io/mcp endpoint.
Can the MCP server execute transactions?
No. The MCP server is currently read-only. It provides data access and swap quotes but does not execute transactions, mint tokens, or modify any on-chain state. Write operations may be added in the future.
What rate limits apply?
The same rate limits from your Xverse API plan apply. If you hit a rate limit, the MCP server will return an error with Retry-After guidance so the AI agent can wait and retry automatically.
I'm getting connection errors — what should I do?
Verify your API key is valid and correctly formatted (UUID format:
8-4-4-4-12hex characters).If using
mcp-remote, make sure you have a recent version of Node.js installed.Try clearing cached auth info:
rm -rf ~/.mcp-authand reconnect.
Which AI clients are supported?
Any client that supports the Model Context Protocol can connect. This includes Claude (Code, Desktop, and claude.ai), Cursor, VS Code, Codex, Windsurf, Zed, and many others. Clients that support Streamable HTTP can connect directly; older clients can use the mcp-remote bridge.
Last updated