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 throughnpx.
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/mcpAdded 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 listChecking MCP server health…
bsv-docs: https://bsvblockchain.com/docs/mcp (HTTP) - ✔ ConnectedThe agent now has three tools to read the docs:
| Tool | What it does |
|---|---|
list_docs | Lists every page with its title, path, address and description |
search_docs | Searches the docs by keywords and returns the best matching pages with a snippet of each, 5 by default and up to 20 |
get_doc | Returns 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/mcpAdded 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 listChecking MCP server health…
bsv-docs: https://bsvblockchain.com/docs/mcp (HTTP) - ✔ Connected
bsv-mcp: npx -y @bsv/mcp - ✔ ConnectedThe agent now has ten tools. The four broadcaster_* tools work with BSV Broadcaster (formerly Arcade), whose public endpoint hostnames still contain arcade:
| Tool | What it does |
|---|---|
broadcaster_submit | Broadcasts 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_status | Reads 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_policy | Reads the fee rate and the size limits of a BSV Broadcaster endpoint |
broadcaster_health | Reads the version, block height and upstream nodes of a BSV Broadcaster endpoint |
check_guardrails | Checks 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_lookup | Returns a BRC as Markdown, by number |
versions_check | Compares the pinned package versions, the Rúnar commit and the BSV Broadcaster version of each known endpoint with the latest ones |
docs_url | Finds the live address of a page of these docs from its id |
code_search, find_function_definition | Search 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-38G-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:
| Variable | Default | What it does |
|---|---|---|
BSV_NETWORK | testnet | testnet or mainnet. Picks the default BSV Broadcaster endpoint and gates Mainnet broadcasts. Any other value stops the server |
BSV_BROADCASTER_URL | Per network | BSV 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_BROADCAST | Not set | 1 lets broadcaster_submit broadcast on Mainnet |
BSV_REPOS_DIR | Not set | The 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:
{
"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:
{
"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:
{
"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 localRemoved 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/patterns | Resource bsv://simple/api |
simple://guide/gotchas | Resource bsv://simple/gotchas |
Prompt integrate_simple | Prompt integrate_simple |
Prompt add_bsv_feature | Prompt add_simple_feature |
Prompt debug_simple | Prompt debug_simple |
scaffold_nextjs_config and the generate_* tools | None |
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:
- Install the BSV blockchain agent skill
- Send a payment with an AI agent
- Broadcast transactions with BSV Broadcaster