> ## Documentation Index > Fetch the complete documentation index at: https://docs.b3os.org/llms.txt > Use this file to discover all available pages before exploring further. # MCP Server Connect Claude to B3OS and build, run, and debug blockchain workflows in plain English. Connect Claude to [B3OS](https://b3os.org) and build, run, and debug blockchain workflows in plain English — no UI, no code, no context-switching. Works with Claude Code, Claude Desktop, and agent teammates. **I Opened a 10x Hyperliquid Long by Talking to Claude** **[npm package](https://www.npmjs.com/package/@b3dotfun/b3os-mcp)** Install from npm. **[MCP Protocol](https://modelcontextprotocol.io)** Learn about the Model Context Protocol. **[Manage API keys](https://b3os.org/organizations/settings?tab=api-keys)** Create or revoke API keys. ## Quick Start **Install** ```bash npm install -g @b3dotfun/b3os-mcp ``` **Run setup** ```bash b3os-mcp-setup ``` The wizard opens your browser, signs you in to B3OS, creates a dedicated API key scoped to this machine, and stores it securely in your OS keychain. Takes about 20 seconds. **Restart Claude** Restart your Claude Code session or Claude Desktop app, and you are done. **One-time setup per machine** You only run the setup once. Re-running issues a new key under the same service account. To revoke a key, visit the API keys page in your org settings. ## What You Can Do ### Build workflows in one sentence ```text "Monitor ETH price every 5 minutes and alert me on Slack if it drops below $2000" "Every Monday at 9am, swap 100 USDC to ETH on Base and email me a confirmation" "When my wallet receives an ERC-20 token, log it to a Google Sheet and send a Telegram alert" ``` Claude searches the action catalog, picks the right triggers and connectors, wires them together, and asks you to review before publishing. ### Query the chain ```text "What's the current price of ETH and BTC?" "What tokens does vitalik.eth hold on Base?" "Why did tx 0xabc... fail?" "Show me the top Polymarket markets right now" ``` No workflow needed — answers come back inline using read-only action queries. ### Debug with full execution context ```text "Why did my last workflow run fail?" "Explain what this node did and how to fix it" ``` Claude pulls the execution trace, identifies which node failed, surfaces the error, and offers a fix you can apply with one more message. ### Operate live workflows ```text "Pause my ETH alert workflow" "Change the Slack channel in my swap notifier" "Re-run last night's failed price snapshot" ``` Claude can list, get, update, publish, pause, resume, run, and trace any workflow you own. ## Available Tools The MCP server exposes 48 tools across seven areas. | Area | Tools | What they do | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | **Action catalog** | `b3os_search_actions`, `b3os_list_actions`, `b3os_get_action`, `b3os_list_logic_actions`, `b3os_list_triggers`, `b3os_get_trigger` | Search and inspect action schemas, trigger schemas, and connector requirements | | **Workflows** | `b3os_create_workflow`, `b3os_build_workflow`, `b3os_get_workflow`, `b3os_update_workflow`, `b3os_validate_workflow`, `b3os_publish_workflow`, `b3os_pause_workflow`, `b3os_resume_workflow`, `b3os_rollback_workflow`, `b3os_delete_workflow`, `b3os_list_workflows`, `b3os_list_workflow_versions`, `b3os_get_workflow_schedule` | Full lifecycle management of workflow drafts and live versions | | **Runs** | `b3os_run_workflow`, `b3os_run_ephemeral`, `b3os_run_action`, `b3os_get_run`, `b3os_list_runs`, `b3os_retry_run`, `b3os_cancel_run`, `b3os_debug_run`, `b3os_test_trigger` | Trigger, trace, retry, and debug workflow executions | | **Data queries** | `b3os_query_action`, `b3os_query_database`, `b3os_get_table_schema`, `b3os_list_tables` | Read-only action proxy and database queries (no CU cost) | | **Lookups** | `b3os_price_lookup`, `b3os_token_lookup`, `b3os_balance_lookup`, `b3os_polymarket_lookup`, `b3os_debug_transaction` | Inline chain data, prices, balances, and tx debugging | | **Organization** | `b3os_whoami`, `b3os_list_wallets`, `b3os_list_connectors`, `b3os_list_connector_types`, `b3os_list_slack_channels`, `b3os_list_telegram_chats`, `b3os_get_cu_balance`, `b3os_logout` | Organization context, wallets, connectors, and billing | | **Templates** | `b3os_list_templates`, `b3os_get_template` | Browse and inspect reusable workflow templates | **Read vs write permissions** Read operations (lookups, listings, schemas, traces) run freely. Write operations — creating workflows, publishing, executing on-chain actions, triggering runs — always require your explicit approval per call. ## Configuration ### Environment variables | Variable | Required | Description | | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `B3OS_API_KEY` | No | API key — on macOS/Windows the key is read from the OS keychain automatically. Set this only on Linux, CI, or to override the keychain. | | `B3OS_SERVER_URL` | No | Override the API endpoint (defaults to B3OS production). | ### CI and headless environments For machines without a browser, create an API key from the B3OS dashboard and set it directly: ```bash export B3OS_API_KEY=b3sk_... ``` ### Manual config The setup wizard handles everything, but if you need to edit your Claude config by hand: ```json macOS / Windows (keystore) { "mcpServers": { "b3os-mcp": { "type": "stdio", "command": "b3os-mcp", "env": { "B3OS_SERVER_URL": "https://api.b3os.org" } } } } ``` ```json Linux / CI (inline key) { "mcpServers": { "b3os-mcp": { "type": "stdio", "command": "b3os-mcp", "env": { "B3OS_API_KEY": "b3sk_your_key_here", "B3OS_SERVER_URL": "https://api.b3os.org" } } } } ``` **nvm and fnm users** If `b3os-mcp` is not resolved — common with Claude Desktop since it does not inherit your shell PATH — replace `"command": "b3os-mcp"` with the absolute node path and the absolute path to `dist/index.js`. The interactive setup handles this automatically. ## Security | Concern | How it is handled | | -------------- | --------------------------------------------------------------------------------------------------------------------------------- | | Key storage | macOS Keychain (encrypted at rest), Windows DPAPI (machine-scoped encryption), Linux `~/.claude/mcp.json` with `0600` permissions | | Key scope | Each install creates a dedicated API key named `b3os-mcp@` | | Wallet keys | Signing happens server-side; private keys are never exposed to Claude or the MCP server | | Session tokens | Discarded immediately after login — only the long-lived API key is persisted | | Write safety | All write operations require explicit user approval per call | | Revocation | Revoke anytime at [b3os.org/organizations/settings?tab=api-keys](https://b3os.org/organizations/settings?tab=api-keys) | ## Setup by Platform The B3OS MCP server works with any client implementing the MCP stdio transport. Below are config snippets for popular editors and AI tools. ```json Claude Code // ~/.claude/mcp.json (auto-configured by b3os-mcp-setup) { "mcpServers": { "b3os-mcp": { "type": "stdio", "command": "b3os-mcp" } } } ``` ```json Claude Desktop // ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) // %APPDATA%\Claude\claude_desktop_config.json (Windows) { "mcpServers": { "b3os-mcp": { "type": "stdio", "command": "b3os-mcp" } } } ``` ```json Cursor // .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global) { "mcpServers": { "b3os-mcp": { "type": "stdio", "command": "b3os-mcp" } } } ``` ```json Windsurf // ~/.codeium/windsurf/mcp_config.json { "mcpServers": { "b3os-mcp": { "type": "stdio", "command": "b3os-mcp" } } } ``` ```json Cline (VS Code) // Settings > Cline > MCP Servers, or .vscode/cline_mcp_settings.json { "mcpServers": { "b3os-mcp": { "type": "stdio", "command": "b3os-mcp" } } } ``` **All clients use the same server** After running `b3os-mcp-setup` once (which stores the API key in your OS keychain), any MCP client on the same machine can connect without additional auth config. ## End-to-End Example This walkthrough shows how an MCP conversation builds a complete workflow from scratch. **Describe your goal** ```text You: "Build a workflow that checks ETH price every hour and sends me a Telegram message if it drops below $2000" ``` **Claude searches the catalog** Claude calls `b3os_search_actions` to find the right price-check and messaging actions, then `b3os_list_triggers` to pick the schedule trigger. It also calls `b3os_list_connectors` and `b3os_list_telegram_chats` to discover your available Telegram bot. **Claude builds the workflow** Claude calls `b3os_build_workflow` with the full definition — a `cronjob` trigger firing every hour, a `coingecko-get-price` action, an `if` condition checking `{{coingecko.result.price}} < 2000`, and a `telegram-send-message` action on the true branch. **You review and approve** Claude presents the workflow graph and asks for confirmation. You approve the write operation. **Test before publishing** Claude calls `b3os_run_ephemeral` to dry-run the workflow with a simulated trigger payload. You see each node result inline. **Publish** Claude calls `b3os_publish_workflow`. The schedule is now live and the first run fires within the hour. **Debug later** ```text You: "My ETH alert workflow failed last night — what happened?" ``` Claude calls `b3os_list_runs` to find the failed execution, then `b3os_debug_run` to surface the failing node and error. It might suggest a fix — like updating the Telegram chat ID — and apply it with `b3os_update_workflow`. ## Troubleshooting **b3os-mcp command not found** Ensure the npm global bin is on your PATH. Run `npm config get prefix` to find the install location, or reinstall with `npm install -g @b3dotfun/b3os-mcp`. **Authentication failed** Re-run `b3os-mcp-setup` to issue a fresh API key, or set `B3OS_API_KEY` explicitly. **Tools not appearing in Claude** Restart your Claude session after setup. Check that `mcp.json` or `claude_desktop_config.json` contains the `b3os-mcp` entry. **Permission denied on writes** Write operations require explicit approval. If you are running in an agent context, ensure the permission mode allows MCP tool calls.