# 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](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#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/mcp ``` Authentication: `Authorization: Bearer ` You can get an API key from the Get Started page. *** ### Claude Code ```bash claude mcp add --transport http xverse https://mcp.secretkeylabs.io/mcp \ --header "Authorization: Bearer " ``` 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: ```json { "mcpServers": { "xverse": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.secretkeylabs.io/mcp", "--header", "Authorization: Bearer " ] } } } ``` *** ### Visual Studio Code `CTRL/CMD` + `P` and search for **MCP: Add Server**. Select **Command (stdio)** and enter: ``` npx mcp-remote https://mcp.secretkeylabs.io/mcp --header "Authorization: Bearer " ``` 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: ```json { "mcpServers": { "xverse": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.secretkeylabs.io/mcp", "--header", "Authorization: Bearer " ] } } } ``` *** ### Codex Run the following command in Terminal: ```bash codex mcp add xverse --url https://mcp.secretkeylabs.io/mcp ``` If this is your first MCP in Codex, enable the `rmcp` feature first: ```toml # ~/.codex/config.toml [features] experimental_use_rmcp_client = true ``` *** ### Windsurf `CTRL/CMD` + `,` to open Windsurf settings. Scroll to **Cascade → MCP servers**, select **Add Server → Add custom server**, and add: ```json { "mcpServers": { "xverse": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.secretkeylabs.io/mcp", "--header", "Authorization: Bearer " ] } } } ``` *** ### Zed `CMD` + `,` to open Zed settings. Add the following: ```json { "context_servers": { "xverse": { "source": "custom", "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.secretkeylabs.io/mcp", "--header", "Authorization: Bearer " ], "env": {} } } } ``` *** ### Others Many tools now support MCP servers. Configure them with the following settings: | Setting | Value | | --------------- | ------------------------------------------------------------------------------------------------ | | **Command** | `npx` | | **Arguments** | `-y mcp-remote https://mcp.secretkeylabs.io/mcp --header "Authorization: Bearer "` | | **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 | Tool | Description | | ------------------------------------- | ---------------------------------------------------------------- | | `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 | Tool | Description | | -------------------------------------- | ------------------------------------------ | | `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 | Tool | Description | | ---------------------------- | -------------------------------------------------------- | | `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 | Tool | Description | | ------------------------------------- | -------------------------------------------- | | `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 | Tool | Description | | -------------------------------- | ----------------------------------------- | | `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 | Tool | Description | | ------------------------------ | ----------------------------------------------------- | | `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? 1. Verify your API key is valid and correctly formatted (UUID format: `8-4-4-4-12` hex characters). 2. If using `mcp-remote`, make sure you have a recent version of Node.js installed. 3. Try clearing cached auth info: `rm -rf ~/.mcp-auth` and reconnect. #### Which AI clients are supported? Any client that supports the [Model Context Protocol](https://modelcontextprotocol.io) 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.xverse.app/api/mcp-server.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.