B3OS MCP Server

Your crypto-native agent, at the speed of conversation.

Plug B3OS into Claude and you get Caddie — the B3OS agent. Not a chatbot that talks about crypto: an agent that acts. It reads the markets, signs and sends transactions, trades perps, moves funds onchain, and stands up automations that keep running after you close the chat. You describe the goal in plain English; Caddie does the work.

Delegate to Caddie — trade Hyperliquid perps · bet on Polymarket · earn on Morpho · swap across Ethereum, Base, Arbitrum & Solana — from Claude Code, Claude Desktop, or your agent teammates.

Top integrations

| Integration | What the agent can do | | ------------------------- | --------------------------------------------------------------------------------- | | Hyperliquid | Trade perps — open/close positions, funding rates, order history, unified account | | Polymarket | Prediction markets — place & redeem bets, market search, trader leaderboards | | Morpho | DeFi lending — deposit, withdraw, live vault yields | | Uniswap + aggregators | Swap via 0x, 1inch, Jupiter, CoW, Relay — including gasless permit swaps | | Multi-chain | Ethereum, Base, Arbitrum, Optimism, Polygon, BNB Chain, and Solana | | Market data | CoinGecko, Coinglass, Dune, DeBank, Zerion, DEX Screener | | Messaging | Slack, Discord, Telegram, Gmail, Twilio SMS, Twitter, Farcaster |

Hundreds more actions across DeFi, privacy (RAILGUN), and business tools — see what's in the box.

Meet Caddie

Caddie is the B3OS agent. b3os is what gives it real hands onchain: managed wallets, gas, transaction confirmation, on-chain triggers, and durable run state. That's the line between an agent that actually moves funds and one that narrates a transaction it never sent.

Ask Caddie a question and it answers inline from live onchain reads — no gas, no state change. Give it a goal and it executes: it picks the right action, shows you the call, and runs it on your approval. Hand it a job that should outlive the conversation — watch a price, act when it moves — and Caddie builds a workflow: a persistent, observable, retryable graph with full execution history that keeps running on the B3OS engine long after you've closed Claude.

You never hold private keys. Signing happens server-side, and every write waits for your explicit approval.

What you can do

Ask anything onchain

"What's the current price of ETH and BTC?"
"What tokens does vitalik.eth hold on Base?"
"What's the funding rate on Hyperliquid for BTC?"
"Show me my Hyperliquid positions"
"Why did tx 0xabc... fail?"
"Show me the top Polymarket markets right now"

Answers come back inline from read-only queries — no gas, no state changes.

Delegate the trade

"Swap 100 USDC to ETH on Base"
"Open a 2x long on ETH perps on Hyperliquid"
"Deposit 500 USDC into the top Morpho vault"
"Send 0.1 ETH to vitalik.eth"

Caddie picks the action, shows you the exact call, and executes it on your approval. Wallet signing is server-side — you never expose a private key.

Hand off a job that keeps running

"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"

For anything that should outlive the chat, Caddie builds a workflow — searches the action catalog, wires the triggers and connectors, and asks you to review before publishing. It runs on the B3OS engine, persistent and retryable, with full execution history.

Operate and debug what's live

"Why did my last run fail?"
"Pause my ETH alert"
"Change the Slack channel in my swap notifier"
"Re-run last night's failed price snapshot"

Caddie pulls the execution trace, points at the failing node, explains the error, and offers a fix you can apply with one more message. It can list, get, update, publish, pause, resume, run, and trace anything you own.

What's in the box

Triggers

Schedule, webhook, manual, EVM smart contract logs, native transfers, ERC-20 receives, token price thresholds (CEX feeds), Polymarket market events, Slack mentions, and external API polling. New trigger types ship continuously.

Chains

B3, Base, Ethereum, Arbitrum, Optimism, Polygon — and 40 EVM chains total — plus Solana for native and SPL token operations. The registry grows continuously; ask Claude which chains are supported for live, current coverage rather than relying on this list. Wallet signing is handled by the platform; you never expose private keys to Claude.

Actions

Hundreds of actions across:

• EVM operations — send native + ERC-20, approve, wrap/unwrap, deploy contracts, arbitrary contract calls
• DEX & swaps — 0x, 1inch, Jupiter, CoW Protocol, Relay, gasless permit swaps
• DeFi — Uniswap v2/v3/v4 liquidity, Morpho deposits/withdrawals, Aerodrome
• Perps & derivatives — Hyperliquid positions, funding rates, order management, unified account; Coinglass liquidations & whale flows
• Privacy — RAILGUN shield/unshield, private transfers
• Market data — CoinGecko, Dune, Sim Dune, DeBank, Zerion, Coinglass, DEX Screener, Token Discovery
• Prediction markets — Polymarket place/redeem/close, market search, trader leaderboards; Kalshi markets
• Social & messaging — Slack, Discord, Telegram, Email (Gmail), Twilio SMS, Twitter, Farcaster (Neynar)
• Business — Shopify, Airtable, Google Sheets, webhooks
• Web & AI — Firecrawl scraping, LLM transformations

Control flow primitives

if, filter, for-each (with nested loop variables), delay, wait (resume on webhook or timeout), format (templating), pluck, regex, code-transform, log, send-webhook, trigger-workflow. Combine these to build branching, looping, and pausing workflows that survive restarts.

Expressions

Reference any prior node's output with {{node.result.field}}, template props with {{$props.key}}, loop items with {{$item}} and {{$index}}, and parent loops with {{$parent_item}}. The expression engine resolves variables at runtime against the persistent execution state.

Quick Start

1. Install

npm install -g @b3dotfun/b3os-mcp

The published npm package ships prebuilt. Building from source isn't supported outside B3's internal monorepo — the build bundles @b3dotfun/b3-workflow-client, a workspace-only package that isn't included in this public mirror. Use npm install -g @b3dotfun/b3os-mcp above instead.

2. Run setup

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 (macOS Keychain or Windows DPAPI). On Linux, the key is written to your Claude config. Takes about 20 seconds.

You only run it once per machine. Re-running issues a new key under the same service account — it does not revoke the old one. To revoke a key, visit b3os.org/organizations/settings?tab=api-keys.

The wizard also offers a Quick start option that skips sign-in entirely: it provisions an anonymous, IP-keyed bootstrap workspace instantly, with its own starter CU grant. This workspace is temporary — it expires after a trial period — and is tied to your IP rather than a real account. The setup output prints a claim URL; visiting it before expiry converts the bootstrap workspace into a permanent account under your login. Prefer Sign in unless you're just trying B3OS out.

3. Restart Claude

Restart your Claude Code session or Claude Desktop app, and you're done.

Having trouble? Run b3os-mcp-setup --diagnose to check your keystore and API key status.

Usage

After setup, just talk to Claude:

You: "What's in my Base wallet?"

Claude: calls the balance lookup and returns the full token breakdown with USD values

Or to act right now:

You: "Open a 2x long on ETH perps on Hyperliquid"

Claude: shows the exact order, then places it on your approval

Or to hand off a standing job:

You: "Swap any stablecoin I receive on Base into ETH and send me a Slack DM"

Claude: plans the job with Caddie, wires the trigger and connectors, and asks you to review before it goes live

Or to debug:

You: "My last run failed — what happened?"

Claude: pulls the execution trace, points at the failing node, explains the error, and offers a fix

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 / headless environments

For machines without a browser (CI runners, headless servers), create an API key from the B3OS dashboard and inject it via your CI platform's secrets management (e.g., GitHub Actions secrets, Doppler, Vault). The runtime reads the B3OS_API_KEY environment variable automatically — no wizard needed.

Manual config (advanced)

The setup wizard handles everything, but if you need to edit your Claude config by hand:

On macOS or Windows (with keystore support): the env block should contain only B3OS_SERVER_URL. The API key is read from the OS keystore at runtime:

{
  "mcpServers": {
    "b3os-mcp": {
      "type": "stdio",
      "command": "b3os-mcp",
      "env": {
        "B3OS_SERVER_URL": "https://api.b3os.org"
      }
    }
  }
}

On Linux (no keystore): the setup wizard writes the API key into the env block automatically. If you need to configure manually, run pnpm run setup first — it stores the key and generates the config for you.

nvm / fnm users: If b3os-mcp isn't resolved — common with Claude Desktop since it doesn't inherit your shell's PATH — replace "command": "b3os-mcp" with the absolute node path and the absolute path to dist/index.js. Find your node with which node. The interactive setup handles this automatically.

How Claude uses the server

The MCP server exposes tools across six areas: Caddie itself (chat, build, debug — hand the agent a multi-step job and it plans and wires it), the action catalog (search and inspect), workflows (CRUD + publish/pause/resume), runs (trigger, list, trace), data queries (read-only action proxy), and organization context (whoami, wallets, connectors). Claude picks the right tool for the task and you stay in the conversation.

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.

Security

• Each install creates a dedicated API key scoped to your machine (b3os-mcp@<hostname>)
• macOS: the key is stored in the system Keychain (service b3os-mcp), encrypted at rest by your login password. No plaintext key on disk. Revoke via security delete-generic-password -s b3os-mcp.
• Windows: the key is DPAPI-encrypted at %USERPROFILE%\.b3os\b3os-mcp-key.dpapi. Decryption is scoped to (Windows user x machine) — the file alone is useless without the user's Windows credentials on the same machine.
• Linux: the key is stored in plaintext in ~/.claude/mcp.json with owner-only permissions (chmod 0600). Keychain support via libsecret is possible — open an issue if you need it.
• The Claude config files (~/.claude/mcp.json, claude_desktop_config.json) contain only B3OS_SERVER_URL on macOS/Windows — no API key. On Linux the key is in the config as a fallback.
• Session tokens from the browser login are discarded immediately — only the long-lived API key is persisted
• Wallet signing happens server-side; private keys are never exposed to Claude or to the MCP server
• Revoke anytime at b3os.org/organizations/settings?tab=api-keys
• Write operations (creating workflows, running actions, executing transactions) always require your explicit approval per call

Links

• Platform: b3os.org
• API keys: b3os.org/organizations/settings?tab=api-keys
• MCP Protocol: modelcontextprotocol.io

License

MIT