Set Up Your AI

Start with the CLI. Add the plugin or MCP configuration below when your client needs it; neither is required for a terminal agent.

The combined installer provides the CLI and chain tools:

curl -fsSL https://install.bitbadges.io | sh
bb --version
bb dev skills

If only the SDK package is installed, use bitbadges-cli dev skills instead. Offline discovery and construction do not need an API key or wallet. Configure API access locally when needed; see CLI setup. Do not paste keys into an agent conversation or commit them in project MCP configuration.

The MCP server command uses the binary from that same installation:

bitbadges-builder

The configurations below do not install or update packages when the client starts. The server uses the CLI's configured API access or environment overrides; see MCP configuration. If a desktop client cannot find the command, use the absolute path to the installed binary and restart the client. Browser signing does not require giving the server a private key or mnemonic.

Claude Code#

Plugin (auto-wires the server, adds 8 skills and two slash commands):

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

Plain MCP, no plugin:

claude mcp add bitbadges-builder -- bitbadges-builder

Choose the plugin or a manual registration. If you already have both, inspect the registrations before removing the redundant one. Details: Claude Code Plugin.

Claude Desktop#

claude_desktop_config.json:

{
  "mcpServers": {
    "bitbadges-builder": {
      "command": "bitbadges-builder",
      "args": []
    }
  }
}

Cursor#

.cursor/mcp.json in the project (or ~/.cursor/mcp.json for all projects):

{
  "mcpServers": {
    "bitbadges-builder": {
      "command": "bitbadges-builder",
      "args": []
    }
  }
}

Windsurf#

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "bitbadges-builder": {
      "command": "bitbadges-builder",
      "args": []
    }
  }
}

Codex CLI#

Add this table to ~/.codex/config.toml (do not replace your existing configuration). Codex uses TOML, not the JSON mcpServers format used by some other clients. Export BITBADGES_API_KEY before launching Codex so env_vars can forward it:

[mcp_servers.bitbadges-builder]
command = "bitbadges-builder"
args = []
env_vars = ["BITBADGES_API_KEY"]

Restart Codex after editing, then use /mcp to inspect the server connection. See the official OpenAI MCP documentation for configuration options.

VS Code and GitHub Copilot#

.vscode/mcp.json in the workspace:

{
  "servers": {
    "bitbadges-builder": {
      "type": "stdio",
      "command": "bitbadges-builder",
      "args": []
    }
  }
}

Zed#

settings.json (zed: open settings):

{
  "context_servers": {
    "bitbadges-builder": {
      "source": "custom",
      "command": "bitbadges-builder",
      "args": []
    }
  }
}

Any LLM Without Tools#

Claude.ai, ChatGPT, Gemini, or any chat model with no MCP access can still build. Ask it for the transaction JSON and take that JSON to the site to review and sign.

1. Give the model context: paste the relevant skill page, or the prompt from agent.exportPrompt() on the Programmatic Agent.

2. Ask for the transaction object and nothing else:

   Return only a JSON object of the form { "messages": [{ "typeUrl": "/tokenization.MsgCreateCollection", "value": { "creator": "bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d", ... } }] } with the rest of value filled in. No prose, no code fence.

3. Paste it into https://bitbadges.io/mint/local-builder ("Bring your transaction"). Or, if you have the CLI, bb preview tx.json --open gives you a short review link, and a #tx=<base64url JSON> link opens the same page with the transaction in the URL hash.

A complete one-message example the model can return, revoking an outgoing approval:

{
  "messages": [
    {
      "typeUrl": "/tokenization.MsgDeleteOutgoingApproval",
      "value": {
        "creator": "bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d",
        "collectionId": "2",
        "approvalId": "agent-daily-budget"
      }
    }
  ]
}

The same transaction as a hash link, which any chat can hand to the user:

https://bitbadges.io/mint/local-builder#tx=eyJtZXNzYWdlcyI6W3sidHlwZVVybCI6Ii90b2tlbml6YXRpb24uTXNnRGVsZXRlT3V0Z29pbmdBcHByb3ZhbCIsInZhbHVlIjp7ImNyZWF0b3IiOiJiYjFwMHJyZWwzMzY1c2NhZHE1azlwdjB4MHpwOWoyMmpzNmRudzcwZCIsImNvbGxlY3Rpb25JZCI6IjIiLCJhcHByb3ZhbElkIjoiYWdlbnQtZGFpbHktYnVkZ2V0In19XX0

The site runs review, transferability, and permissions checks before the wallet signature, so an unvalidated model output still gets the same review as a tool-built one.

Verify#

bb doctor                                  # chain binary, CLI, API key, network
bb dev tools list --names | jq -r '.data.names[]'   # the same registry your client sees

In an MCP client, run this prompt and inspect the actual tool-call result, rather than a prose answer alone:

Call get_current_timestamp and show its returned timestamp.

For a first task, ask: “Prepare an unsigned invoice for one payer. Use the installed schema, tell me any missing payment terms, and save the proposal for review.” Once the terms are correct, use the main-wallet payment flow to request a signature. A successful discovery call verifies connectivity, not permission to spend.

Related#

• MCP Builder Tools
• Claude Code Plugin
• Agents