BSV blockchainBSV blockchain

Connect your AI tool with MCP

Connect Claude Code to the BSV blockchain docs and tools through MCP, the Model Context Protocol an AI tool uses to call an outside server for information. With them, your agent searches and reads these pages before it writes code for the BSV blockchain, and checks transactions and projects with those tools. Use it when an AI agent builds your BSV blockchain app. Without a source, the agent can pick the wrong network or put a private key in your code. At the end, the docs server and @bsv/mcp are connected to your project, and the agent has checked a project against the BSV blockchain guardrails.

Before you begin

  • Claude Code installed. This guide was tested with Claude Code 2.1.303.
  • Node.js 22 or newer, for @bsv/mcp, which runs through npx.

How it works

Two MCP servers give the agent knowledge of the BSV blockchain in different ways. The BSV blockchain docs server runs at https://bsvblockchain.com/docs/mcp, and @bsv/mcp is a package that runs on your machine:

  • BSV docs server
    Gives the agent
    Search and full pages of these docs, as Markdown
    Use it for
    Answers and code that follow these guides, starting on testnet
  • @bsv/mcp
    Gives the agent
    Tools for BSV Broadcaster, a guardrail check, BRCs and versions, with dated facts
    Use it for
    Actions and live values, on testnet by default

Claude Code adds each server to the current project only, so run the commands in your project folder.

The bsv-dev plugin of Install the BSV blockchain agent skill already connects both servers, as plugin:bsv-dev:bsv-docs and plugin:bsv-dev:bsv-mcp. With the plugin, skip the two claude mcp add commands on this page, or Claude Code starts a second copy of bsv-mcp. The tools, the guardrail check and the settings below are the same.

Connect the BSV blockchain docs server

The docs server runs on this site and needs no login or API key:

Add the server

Add the server under the name bsv-docs:

claude mcp add --transport http bsv-docs https://bsvblockchain.com/docs/mcp
Added HTTP MCP server bsv-docs with URL: https://bsvblockchain.com/docs/mcp to local config
File modified: /Users/you/.claude.json [project: /Users/you/my-app]

The name is the one Claude Code shows for the server. Keep bsv-docs, since the bsv-dev rules and the skill look for the server under that name.

Check the connection

List the servers in the project:

claude mcp list
Checking MCP server health…

bsv-docs: https://bsvblockchain.com/docs/mcp (HTTP) - ✔ Connected

The agent now has three tools to read the docs:

ToolWhat it does
list_docsLists every page with its title, path, address and description
search_docsSearches the docs by keywords and returns the best matching pages with a snippet of each, 5 by default and up to 20
get_docReturns one or more pages in full, as Markdown, by path or address

Ask Claude Code a question about the BSV blockchain in the same project, and it calls search_docs and get_doc before it answers. For a first payment, the docs lead the agent to Send a payment from a web app, where a testnet wallet in BSV Desktop approves the payment and no private key goes in your code.

The page addresses in the results use bsvblockchain.com/docs. To read a page, the agent passes its path to get_doc, which works with or without the site address.

Add @bsv/mcp

@bsv/mcp is BSV Association’s MCP server for building apps, testnet first. Its source is in bsv-blockchain/bsv-ai-toolkit. It replaces @bsv/simple-mcp, as described in Where Simple MCP went. This section uses @bsv/mcp 2.0.1.

Add the server

Add the server under the name bsv-mcp, on testnet:

claude mcp add bsv-mcp -e BSV_NETWORK=testnet -- npx -y @bsv/mcp
Added stdio MCP server bsv-mcp with command: npx -y @bsv/mcp to local config
File modified: /Users/you/.claude.json [project: /Users/you/my-app]

Testnet is the default, and BSV_NETWORK=testnet keeps the network visible in the configuration. Claude Code starts the server through npx, which downloads the package the first time.

Check the connection

List the servers again:

claude mcp list
Checking MCP server health…

bsv-docs: https://bsvblockchain.com/docs/mcp (HTTP) - ✔ Connected
bsv-mcp: npx -y @bsv/mcp - ✔ Connected

The agent now has ten tools. The four broadcaster_* tools work with BSV Broadcaster (formerly Arcade), whose public endpoint hostnames still contain arcade:

ToolWhat it does
broadcaster_submitBroadcasts a signed transaction, as raw or EFExtended Format (BRC-30): the raw transaction plus the satoshis and locking script of every output it spends hex, to BSV Broadcaster and reads its status back. It refuses BEEFBackground Evaluation Extended Format (BRC-62): a transaction with the evidence a host needs to verify it. On Mainnet it also needs BSV_MCP_ALLOW_MAINNET_BROADCAST=1
broadcaster_statusReads the status of a transaction from BSV Broadcaster and says whether it is final for an app: SEEN_ON_NETWORK or later with no competing transaction
broadcaster_policyReads the fee rate and the size limits of a BSV Broadcaster endpoint
broadcaster_healthReads the version, block height and upstream nodes of a BSV Broadcaster endpoint
check_guardrailsChecks a project against the BSV blockchain guardrails G-01 to G-38 and lists each finding with its fix. It reads the project and changes nothing
brc_lookupReturns a BRC as Markdown, by number
versions_checkCompares the pinned package versions, the Rúnar commit and the BSV Broadcaster version of each known endpoint with the latest ones
docs_urlFinds the live address of a page of these docs from its id
code_search, find_function_definitionSearch local clones of the BSV blockchain repositories, made with setup.sh from the repository, in the folder set in BSV_REPOS_DIR

The server also has 16 resources for the agent to read. Ten are dated facts, bsv://facts/*, on networks, BSV Broadcaster (bsv://facts/bsv-broadcaster), fees, WhatsOnChain, wallet limits, consensus, Rúnar, 1Color tokens, payment channelsTwo parties lock funds in one output and exchange signed updates off the network. Only the last update is broadcast and versions. Each fact starts with the date it was verified, so the agent can tell how current it is. The other six are the guardrails, bsv://guardrails, the custody shapes, the threat model, the docs index, and the @bsv/simple 0.7 API and its traps. Two templates read one guardrail, as bsv://guardrails#G-09 for example, and any BRC, as bsv://brc/{id}.

It also has five prompts: review_against_guardrails runs the guardrail check and fixes the errors, tokenize_with_1color gives the encoding of 1Color token outputs, and integrate_simple, add_simple_feature and debug_simple work with @bsv/simple.

broadcaster_submit refuses a Mainnet broadcast, before it contacts BSV Broadcaster, unless BSV_MCP_ALLOW_MAINNET_BROADCAST=1 is set in the shell that starts the agent. The gate goes by the network of the call, never by the address: the network the agent passes, or BSV_NETWORK when it passes none. A custom BSV_BROADCASTER_URL that points at Mainnet needs BSV_NETWORK=mainnet. Under BSV_NETWORK=testnet, the server treats that endpoint as testnet, and the gate does not apply. A Mainnet broadcast spends real BitcoinSV (BSV) and cannot be undone.

Check a project against the guardrails

The guardrails are the rules a BSV blockchain app follows, such as broadcasting through BSV Broadcaster and keeping keys in the wallet. check_guardrails is the quickest tool to try, since it needs no wallet and no coins:

Ask for the check

In Claude Code, in your project folder, type the request:

Check this project against the BSV guardrails.

The agent calls check_guardrails with the absolute path of the project. The tool refuses a relative path.

Read the report

The report starts with the number of errors and warnings, then lists each finding with its guardrail, file and line, the fix, and a reference to the guardrail. For a project that broadcasts through the ARC class of the SDK, it looks like this, shortened:

check_guardrails: 15 errors, 5 warnings, shape A
...
error G-09 src/broadcast.ts:6  export const arc = new ARC('https://arc.taal.com', { deploymentId: 'tipjar' })
  fix: Broadcast only through BSV Broadcaster (`POST /tx`, text/plain, EF when sources are attached, never BEEF); never the SDK `ARC` class or `/v1/tx`; `BSV_BROADCASTER_URL` configurable with the public instance per network as default. (bsv://guardrails#G-09)
...
passed: G-04
not applicable: G-08, G-17, G-18, G-19, G-23, G-24, G-36
manual checklist: G-05, G-07, G-11, G-13, G-20, G-22, G-26, G-27, G-28, G-29, G-30, G-32, G-33, G-35, G-37, G-38

G-09 is the rule to broadcast only through BSV Broadcaster, and the ARC class calls a path BSV Broadcaster does not serve. An error is a finding to fix, and a warn is one to check. shape A means the user’s wallet holds the keys. A guardrail is not applicable when the project has nothing it covers. The tool cannot check the guardrails in the manual checklist from the code, so the agent reviews those by hand.

For payment channels, the tool checks G-36 in the code: every lock time is in seconds or a block height, never in milliseconds. The other channel guardrails, G-35, G-37 and G-38, are in the manual checklist. The tool also checks G-08 in the code, a rule for any app that signs a digest: the app signs only a digest it rebuilt itself, never one it received over the wire.

A project is ready when the report shows 0 errors. The repository’s tipping sample, samples/tipping-shape-a, reports 0 errors, 0 warnings, as Start from the tipping sample shows. To keep a finding that you checked and accept, add // bsv-guardrail-ignore GUARDRAIL_ID REASON on the flagged line or the line above. Replace GUARDRAIL_ID with the id of the guardrail, such as G-09, and REASON with why you accept the finding. In a file with other comments, start it with #, <!-- or /* instead of //. Every guardrail is listed in content/guardrails.yaml.

Set the environment

@bsv/mcp reads these variables, which you pass with -e in claude mcp add. The plugin sets BSV_NETWORK and BSV_BROADCASTER_URL from its bsv_network and broadcaster_url settings:

VariableDefaultWhat it does
BSV_NETWORKtestnettestnet or mainnet. Picks the default BSV Broadcaster endpoint and gates Mainnet broadcasts. Any other value stops the server
BSV_BROADCASTER_URLPer networkBSV Broadcaster base URL. Default on testnet https://arcade-v2-testnet-us-1.bsvblockchain.tech, on Mainnet https://arcade-us-1.bsvblockchain.tech. A host that belongs to the other network stops the server
BSV_MCP_ALLOW_MAINNET_BROADCASTNot set1 lets broadcaster_submit broadcast on Mainnet
BSV_REPOS_DIRNot setThe folder of BSV blockchain repository clones made with setup.sh, for code_search and find_function_definition

The server still reads ARCADE_URL, the former name of BSV_BROADCASTER_URL, when BSV_BROADCASTER_URL is not set. It is deprecated, and the server logs a warning when it uses it.

Set BSV_NETWORK=mainnet for any Mainnet BSV Broadcaster endpoint, including your own. The server goes by the network you set, not by the address: it refuses the known Mainnet hosts on testnet, but it cannot tell where an unknown host belongs, so it treats an unknown Mainnet endpoint under BSV_NETWORK=testnet as testnet, without the Mainnet gate.

The testnet default is the host that Broadcast transactions with BSV Broadcaster uses. arcade-testnet-us-1, the default of @bsv/mcp 2.0.0, still works and counts as testnet; set BSV_BROADCASTER_URL to use it.

Use another AI tool

Cursor, Windsurf and VS Code take the same two servers as JSON. Each configuration adds both servers; remove the bsv-mcp entry if you want only the docs:

Cursor #

Add to .cursor/mcp.json:

.cursor/mcp.json
{
  "mcpServers": {
    "bsv-mcp": {
      "command": "npx",
      "args": ["-y", "@bsv/mcp"],
      "env": { "BSV_NETWORK": "testnet" }
    },
    "bsv-docs": {
      "url": "https://bsvblockchain.com/docs/mcp"
    }
  }
}
Windsurf (Devin Desktop) #

Windsurf is now named Devin Desktop. Add to ~/.config/devin/mcp_config.json on macOS and Linux, or %APPDATA%\devin\mcp_config.json on Windows, as its MCP documentation says. It names the URL field serverUrl:

~/.config/devin/mcp_config.json
{
  "mcpServers": {
    "bsv-mcp": {
      "command": "npx",
      "args": ["-y", "@bsv/mcp"],
      "env": { "BSV_NETWORK": "testnet" }
    },
    "bsv-docs": {
      "serverUrl": "https://bsvblockchain.com/docs/mcp"
    }
  }
}
VS Code #

Add to .vscode/mcp.json. VS Code uses a top-level servers key instead of mcpServers:

.vscode/mcp.json
{
  "servers": {
    "bsv-mcp": {
      "command": "npx",
      "args": ["-y", "@bsv/mcp"],
      "env": { "BSV_NETWORK": "testnet" }
    },
    "bsv-docs": {
      "type": "http",
      "url": "https://bsvblockchain.com/docs/mcp"
    }
  }
}

These configurations come from the install notes of @bsv/mcp and were not run for this guide.

Remove a server

Run claude mcp remove with the name of the server, in the project folder where you added it. -s local is the scope that claude mcp add uses. To remove both servers, for example before you install the plugin:

claude mcp remove bsv-docs -s local
claude mcp remove bsv-mcp -s local
Removed MCP server bsv-docs from local config
File modified: /Users/you/.claude.json [project: /Users/you/my-app]
Removed MCP server bsv-mcp from local config
File modified: /Users/you/.claude.json [project: /Users/you/my-app]

Where Simple MCP went

@bsv/mcp replaces @bsv/simple-mcp. The table below shows where each resource and prompt went. If your project still has @bsv/simple-mcp, remove it with claude mcp remove simple-mcp -s local and add @bsv/mcp as above.

Resources and prompts that moved #
@bsv/simple-mcp 0.0.2@bsv/mcp 2.0.1
simple://api/*, simple://guide/nextjs, simple://guide/patternsResource bsv://simple/api
simple://guide/gotchasResource bsv://simple/gotchas
Prompt integrate_simplePrompt integrate_simple
Prompt add_bsv_featurePrompt add_simple_feature
Prompt debug_simplePrompt debug_simple
scaffold_nextjs_config and the generate_* toolsNone

The code generators have no replacement. The prompts guide the agent to write the code itself, testnet first.

Next steps

With both servers connected, give the agent the BSV blockchain playbook, which in Claude Code replaces these servers with the plugin’s, then let it build a first payment: