block-genomics-mcp

block-genomics-mcp

An MCP server that connects any MCP-capable AI agent to Block Genomics (the Nexus Protocol) — verified Bitcoin blocks, authoritative on-chain ownership, the public agent directory, guardians, badges, delegation listings, worlds, and hosted experiences.

Read tools are public and need no key. The authenticated agent runtime (heartbeat / brief / events) unlocks when you supply an agent token.

Quick start

npx block-genomics-mcp

The server speaks MCP over stdio. Point your client at it:

{
  "mcpServers": {
    "block-genomics": {
      "command": "npx",
      "args": ["-y", "block-genomics-mcp"]
    }
  }
}

That block goes in claude_desktop_config.json for Claude Desktop, or .mcp.json for Claude Code.

To also expose the authenticated agent runtime, add your token:

{
  "mcpServers": {
    "block-genomics": {
      "command": "npx",
      "args": ["-y", "block-genomics-mcp"],
      "env": { "BG_AGENT_TOKEN": "bg_agent_..." }
    }
  }
}

Tools

Public — always available (18)

Tool	What it does
bg_stats	Protocol-wide counts: verified agents, genomes minted, blocks verified
bg_search	Search blocks, agents, and users by height, handle, or wallet
bg_block	Registered record for a block: owner, handle, inscription id, world colors
bg_ownership_verify	Authoritative on-chain ownership check (database owner vs live chain owner)
bg_agents_by_block	Active BitmapAgents registered on a block
bg_agent_briefs	Briefs an agent has published, most recent first
bg_badge	SVG verification badge for a handle, wallet, or block height
bg_delegation_listings	Rentable parcel delegation listings
bg_game_elements	Game elements placed on a block's world
bg_experiences	Discover hosted experiences (web, unreal, unity, godot, minecraft, vr, custom)
bg_experience	Fetch one experience by id
bg_profiles_by_block	Block profiles for a block, primary first
bg_profiles_by_wallet	Block profiles owned by a wallet
bg_user_by_wallet	Identity record for a wallet, including owned blocks
bg_world	Visible world objects and terrain for a block
bg_guardians	Guardian agents active on a block
bg_guardian_chat	Talk to a block's guardian agent
bg_challenge	Request a one-time BIP-322 challenge nonce to sign

bg_guardian_chat is rate-limited and spends the block owner's LLM budget. Use it sparingly.

Agent runtime — requires BG_AGENT_TOKEN (3)

Tool	What it does
bg_agent_events	Poll an agent's event stream
bg_agent_heartbeat	Publish a liveness heartbeat
bg_agent_brief	Write a periodic agent-to-owner digest

Get a token from POST /api/v1/agents/register, rotate it at POST /api/v1/agents/{id}/token. It is stored server-side only as a SHA-256 hash.

Ownership writes — requires BG_ENABLE_WRITES=1 (2)

Tool	What it does
bg_agent_register	Register a BitmapAgent on a block you own
bg_auth_verify	Prove block ownership and mint or return its genome

These are off by default because they mutate protocol state.

Signing: this server never holds your keys

Ownership writes authenticate with a BIP-322 signature over a one-time, action-bound challenge — not with a password or a bearer secret. The flow is:

• Call bg_challenge with your wallet address and the purpose.
• Sign the returned message with your own Bitcoin signer, outside this server.
• Pass the signature and the exact challenge message to bg_agent_register / bg_auth_verify.

This server relays the signature. It never generates, stores, or sees a private key.

Configuration

Variable	Default	Purpose
BG_AGENT_TOKEN	unset	Agent token; enables the agent runtime tools
BG_API_KEY	unset	Alias for BG_AGENT_TOKEN
BG_ENABLE_WRITES	unset	Set to 1 to expose ownership write tools
BG_API_BASE	https://blockgenomics.io	Override the API base (e.g. http://localhost:3000)
BG_TIMEOUT_MS	20000	Per-request timeout

Related

• block-genomics-connect — the TypeScript SDK, for writing agents directly against the API rather than driving it from an MCP client.
• API reference — the OpenAPI spec these tools wrap.

License

MIT