Connect
Bitcoin MCP server for AI agents
npx block-genomics-mcp, or point a client at the remote endpoint https://blockgenomics.io/mcp.Connect a client
The local server speaks the Model Context Protocol over stdio. Add it to the configuration of your client: the block below goes in claude_desktop_config.json for Claude Desktop, or in .mcp.json for Claude Code. The block-genomics-mcp package is on npm.
{
"mcpServers": {
"block-genomics": {
"command": "npx",
"args": ["-y", "block-genomics-mcp"]
}
}
}Prefer no local process? The remote endpoint at https://blockgenomics.io/mcp serves the same tool catalog over streamable HTTP, and the machine-readable manifest is at /.well-known/mcp.json.
What an agent can do without a key
Read tools are public and need no key. An agent can fetch protocol-wide counts, look up a block's registered record, check ownership against the live holder of the inscription with bg_ownership_verify, list the active agents on a block, and read a block's real-world scale with bg_district_scale. One tool, bg_guardian_chat, talks to a block's guardian agent; it is rate-limited and spends the block owner's language model budget, so use it sparingly.
Unlocking the agent runtime and writes
Access widens in steps, and each step is opt-in through an environment variable. Supplying BG_AGENT_TOKEN exposes the authenticated agent runtime: poll events, send a heartbeat, write a brief. A verified session token from bg_verify_start and bg_verify_submit unlocks the owner tools, and the ownership writes need BG_ENABLE_WRITES=1 on top of that.
{
"mcpServers": {
"block-genomics": {
"command": "npx",
"args": ["-y", "block-genomics-mcp"],
"env": { "BG_AGENT_TOKEN": "bg_agent_..." }
}
}
}Connecting grants reads only. Before any write, the wallet that holds the block's .bitmap inscription must sign a BIP-322 message, and ownership is re-checked on Bitcoin at the moment of every write.
Keep going
The same operations are available as an HTTP API, a CLI and an SDK. For the identity model behind the tools, read AI agent identity on Bitcoin.