MCP Builder Tools

The MCP builder tools let an AI assistant build, review, simulate, and query BitBadges transactions. The CLI is the primary entry point; MCP adapts the shared tool registry for clients that prefer structured tool calls. The installed registry in bitbadgesjs-sdk/src/builder/tools/ is authoritative when this reference and an installed version differ.

# Install globally
npm install -g bitbadges

# Start the MCP server from that same installation
bitbadges-builder

To build from your own Node code with the same tools and no MCP client, use the Programmatic Agent. For terminal workflows without an MCP client, use the CLI.

Schemas and Examples#

bb dev capabilities
bb dev capabilities build_subscription
bb dev tools call build_subscription --args-file subscription.json

The compact catalog lists operation IDs and CLI/MCP entry points. Requesting one ID includes its inputSchema; the standard builders also include a sample in inputSchema.examples. The equivalent MCP call is get_capabilities with {"id":"build_subscription"}. schemaVersion identifies the catalog format and catalogHash identifies its installed definitions.

Eighteen existing standard builders are exposed through this adapter, including subscriptions, auctions, bounties, crowdfunds, product catalogs, smart tokens, credits, and approval templates. They use the same core functions as the CLI. PaymentRequestV2 remains available as build_payment_request_v2, including invoice substandards. The catalog also exposes standard actions through the installed CLI, including standard_credit_tokens_quote for exact credit purchase units. Native Cosmos commands remain CLI-only; inspect the installed catalog rather than guessing a tool name.

The schemas enforce JSON shape and unknown-field rejection. Each builder also applies its existing runtime rules; schema validity alone does not prove a payment is authorized or will succeed on chain. IDs and integer base-unit amounts use strings where declared; older display-unit builder parameters use numbers. Returned approval amounts are encoded as decimal strings. Examples are unsigned proposals with sample addresses, IDs and metadata URLs; replace them, set the real signer, review, and simulate before requesting a signature.

Client Configuration#

Claude Desktop#

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "bitbadges-builder": {
      "command": "bitbadges-builder",
      "args": [],
      "env": {
        "BITBADGES_API_KEY": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
      }
    }
  }
}

The key is a fake example. Configure your own key from bitbadges.io/developer locally. Building proposals does not require a mnemonic. Use main-wallet requests for browser signing.

Claude Code#

After the chain and CLI install (curl -fsSL https://install.bitbadges.io | sh), add the server by hand:

claude mcp add bitbadges-builder -- bitbadges-builder

Or install the Claude Code Plugin, which wires the same server and adds 8 workflow skills plus /bitbadges:setup and /bitbadges:status:

/plugin marketplace add BitBadges/bitbadges-plugin
/plugin install bitbadges

The plugin is a convenience layer. The CLI install is what runs underneath.

Cursor#

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "bitbadges-builder": {
      "command": "bitbadges-builder",
      "args": [],
      "env": {
        "BITBADGES_API_KEY": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
      }
    }
  }
}

Environment Variables#

The MCP server does not need wallet private keys or mnemonics. Signing happens through the separately authorized CLI or wallet flow. It does not read ANTHROPIC_API_KEY or OPENAI_API_KEY; your client provides the model.

Tools#

Params marked * are required. Session tools also accept sessionId and creatorAddress (bb1 or 0x form) for per-request isolation; those two are omitted from the tables.

A complete call, as the client sends it and as bb dev tools call add_approval --args-file ./approval.json reads it. This adds a public mint of Demo Coin (collection token ID 1) with at most 10 units per address:

{
  "sessionId": "demo-coin",
  "creatorAddress": "bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d",
  "approvalId": "public-mint",
  "fromListId": "Mint",
  "toListId": "All",
  "initiatedByListId": "All",
  "tokenIds": [{ "start": "1", "end": "1" }],
  "transferTimes": [{ "start": "1", "end": "18446744073709551615" }],
  "ownershipTimes": [{ "start": "1", "end": "18446744073709551615" }],
  "approvalCriteria": {
    "overridesFromOutgoingApprovals": true,
    "overridesToIncomingApprovals": true,
    "approvalAmounts": {
      "overallApprovalAmount": "0",
      "perToAddressApprovalAmount": "10",
      "perFromAddressApprovalAmount": "0",
      "perInitiatedByAddressApprovalAmount": "0",
      "amountTrackerId": "public-mint",
      "resetTimeIntervals": { "startTime": "0", "intervalLength": "0" }
    }
  }
}

The tool answers with the approval as stored in the session plus any validation notes.

Standard Actions#

Prefer the high-level builder or action when it fits. The standard_* tools cover payment requests, subscriptions, smart tokens, credits, products, auctions, crowdfunds, bounties, and prediction markets. Inputs come from the CLI command definitions, and results preserve the CLI JSON envelope. They query state or prepare unsigned messages; they never sign or broadcast.

bb dev capabilities standard_pay_requests_pay
bb pay-requests pay 46 --creator "$PAYER" --obligation payment-1 --units 1 --mainnet

Equivalent MCP arguments for standard_pay_requests_pay:

{
  "collectionId": "46",
  "creator": "bb1zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zql3w7",
  "obligation": "payment-1",
  "units": "1",
  "mainnet": true
}

Replace the sample collection and payer. Action amounts are strings, preserving CLI decimal text; units follow that command's help. Signing, credential, endpoint, shell, and file-output arguments are excluded. The adapter starts bitbadges-cli directly with literal arguments and checks its capability hash before running the action. Install CLI and MCP from the same SDK version. BITBADGES_CLI_PATH can select a trusted installed CLI executable when the client cannot find it on PATH; it is operator configuration, not a tool argument.

For subscriptions, standard_subscriptions_claim prepares one payment; standard_subscriptions_subscribe also requests recurring consent. Renewal and cancellation require a successful read of existing approvals so unrelated consent is preserved. Do not infer refunds or prorations from cancellation.

For browser handoff use the CLI's --browser flow. list_signing_requests lists local request IDs; signing_request_status accepts requestId and optional resume: true. Resume returns the original signing URL only while its listener is active. These tools do not initiate payment or verify chain execution. See request recovery.

Session Builders#

Each tool sets one field on a session-scoped transaction. Calls in the same round can run in parallel. Tools that need the API key say so.

generate_placeholder_art (seed*, style, monogram) still exists in source but is not in the MCP catalog: get_transaction fills blank images for you.

Helper Builders#

Review and Analysis#

Simulation and Validation#

Queries#

All query tools need BITBADGES_API_KEY.

Component Generators#

Stateless helpers that return one piece of a collection.

Utilities#

Instructions and Docs#

Rendered skill pages: Skills.

Workflows#

Session-Based Build#

Ask your agent:

Build a fungible token called Demo Coin with a 1,000,000 supply cap and a public mint of up to 10 per address. Use the session tools, run validate, review, and simulate in parallel, fix any critical findings, then call get_review_url and give me the link.

The prompt above produces this chain:

set_standards + set_valid_token_ids + set_invariants + add_approval + set_permissions + set_default_balances + set_collection_metadata + set_token_metadata
  -> (optional) add_transfer (auto-mint at creation)
  -> validate_transaction + review_collection + simulate_transaction (in parallel)
  -> fix errors with remove_approval + re-add (max 3 attempts)
  -> get_transaction (final JSON)
  -> get_review_url (link the user opens to review and sign)

1. Build. Call the per-field tools in parallel: standards, token IDs, invariants, approvals, permissions, metadata, balances.
2. Auto-mint (optional). Call add_transfer to append a MsgTransferTokens next to the collection creation.
3. Verify. Call validate_transaction, review_collection, and simulate_transaction in parallel. Fix errors with a targeted remove_approval and re-add.
4. Export. Call get_transaction for the final JSON.
5. Hand off. Call get_review_url and give the user reviewUrl. Prefer the link over pasting JSON: it is short and cannot be corrupted in transit.

Query and Verification (No Signing)#

query_collection -> verify_ownership -> (act on the result)

Auto-Mint at Creation#

add_transfer mints to specific addresses in the same transaction as the collection creation. The transaction then holds two messages: MsgCreateCollection and MsgTransferTokens. (The session holds it as MsgUniversalUpdateCollection; get_transaction narrows it on the way out.) Use it for "mint 100 tokens to myself", "distribute tokens to the team", or "auto-mint at creation".

1. Build the collection with a mint approval (add_approval with fromListId: "Mint" and initiatedByListId: <creator address>).
2. Call add_transfer with the recipient addresses, balances, and prioritizedApprovals that reference the mint approval.
3. Verify and export as normal. The transaction contains both messages.

Maximum 4 transfer messages per transaction.

Hand Off to the Browser#

The builder never signs or broadcasts. Three exits:

• get_review_url returns reviewUrl, where the user reviews and signs with a browser wallet. It is backed by a prv_ code from POST /api/v0/builder/preview. Uploading the preview needs BITBADGES_API_KEY; opening the returned link needs none, because the unguessable code is the secret. The code expires in 1 hour. BITBADGES_FRONTEND_URL or the frontendUrl param points the link at testnet or a local site; a testnet BITBADGES_API_URL infers https://testnet.bitbadges.io.
• Save get_transaction output to a file and run bb preview tx.json --open, or bb deploy --browser / --burner from the CLI.
• Sign with the SDK signing client.

Resources#

The server also exposes embedded documents as MCP resources. Read them with your client's resource support or with bb dev resources read bitbadges://recipes/all.

Call Tools from the CLI#

The same registry is reachable from bb dev as plain function calls, with no MCP round-trip.

bb dev tools list                              # full schemas, as JSON
bb dev tools list --names                      # `{ ok, data: { names: [...] } }` envelope; pipe to jq -r '.data.names[]'
bb dev tools call get_current_timestamp
bb dev tools call get_skill_instructions --args '{"skillId":"smart-token"}'
bb dev tools call set_collection_metadata --args-file ./metadata.json --session demo

Stateful tools (set_*, add_*, remove_*, get_transaction) read and write the named session. Sessions survive across invocations, so an agent can compose a collection across many calls:

SESSION=demo-coin
bb dev tools call set_standards --session $SESSION --args '{"standards":["Fungible Tokens"]}'
bb dev tools call set_valid_token_ids --session $SESSION --args '{"tokenIds":[{"start":"1","end":"1"}]}'
bb dev tools call set_collection_metadata --session $SESSION --args '{"name":"Demo Coin","description":"One million units of token ID 1.","image":"ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/coin.png"}'
bb dev tools call add_approval --session $SESSION --args-file ./approval.json     # the public-mint call from the Tools section
bb dev tools call get_transaction --session $SESSION

Unknown tool names exit 1 and print the available tools on stderr.

bb session list                       # session ids on disk
bb session show demo                  # snapshot as JSON
bb session reset demo                 # delete the file

bb dev resources list                 # full metadata as JSON
bb dev resources list --uris          # URIs only
bb dev resources read bitbadges://recipes/all

Flag-based template builders (bb build <template>) are faster than composing tool calls when a template fits: Build.

Related#

• Programmatic Agent
• Claude Code Plugin
• Skills
• Dev commands