Skip to main content

​
Float on your machine — Agent Playbook

Step-by-step guide for AI agents to install and configure Float. The goal is to complete setup with as little human involvement as possible.
You, the agent, should check and install prerequisites on behalf of the user. Do not wait — start immediately. Only ask for credentials the user must provide themselves (e.g. a key from their browser).

​
Requirements

Check these before starting. Install or create anything that’s missing.
  • Node.js 18+ and npx on the local machine
  • Claude Code, Cursor, or Codex as the host environment
  • Internet access to install npm packages
  • A browser the user can interact with for the sign-in step (you can open it for them)

​
Step 01 — Verify prerequisites

node --version
npx --version
If Node.js is below 18 or not installed, open the download page: 
# macOS / Linux
open https://nodejs.org

# Or direct the user to: https://nodejs.org/en/download

​
Step 02 — Add Float MCP to Claude Code

Register Float as an MCP server so the user’s agent can call Float tools natively in all future Claude Code sessions. 
claude mcp add float -- npx -y @usefloat/mcp@latest
For Cursor: write to .cursor/mcp.json in the project root or ~/.cursor/mcp.json globally. For Codex: write to the MCP config in the Codex settings directory.
Run the Float CLI init command. It will open the user’s browser to the Float link page. The user signs in once (Google, Apple, email, or wallet) — the rest is automatic. 
npx @usefloat/cli@latest init
What happens:
  1. CLI generates a one-time link token and calls POST /v1/link-sessions on the Float API
  2. The browser opens to https://app.usefloat.xyz/link?token=<token>
  3. User signs in via Privy (Google, Apple, email, Phantom, or Solflare)
  4. Float provisions a Solana wallet for the agent and links it to the owner identity
  5. CLI polls until the session completes, then writes ~/.float/config.json
~/.float/config.json after a successful link: 
{
  "agentId": "your-agent-id",
  "walletAddress": "SolanaWalletAddress...",
  "apiKey": "float_sk_...",
  "linkedAt": "2026-04-22T..."
}
This is a human step — the user must interact with the browser for the sign-in. Open the browser for them, then wait for the CLI to print “Linked.” before proceeding.
npx @usefloat/cli@latest status
Expected output: 
Agent:   your-agent-id
Wallet:  SolanaWalletAddress...
Balance: 0.00 USDC
API:     https://api.usefloat.xyz ✓
If balance is 0, proceed to Step 05. The link is successful regardless of balance.

​
Step 05 — Load USDC into the treasury

Open the Float fund page in the user’s browser. This is a human step — the user must complete the deposit. 
# macOS
open https://app.usefloat.xyz/fund

# Linux
xdg-open https://app.usefloat.xyz/fund
Tell the user:
  • Fiat on-ramp (credit card → USDC) is available on this page
  • Recommended starting deposit: 10–10–25 USDC
  • They only need to do this once — all agents share this treasury balance

​
Step 06 — Test the integration

Start a new Claude Code session with Float MCP active and verify end-to-end: 
claude
Then, as that agent, call: 
Check my Float balance
Float MCP will call check_balance and return the current USDC balance, agent ID, and wallet address. If this works, setup is complete.

​
Step 07 — Troubleshooting

Restart Claude Code to pick up the new MCP registration. Verify with:
claude mcp list
Float should appear in the list. If not, check ~/.claude.json for the mcpServers.float entry.
Re-run with debug output:
npx @usefloat/cli@latest init --debug
Or open the link page manually — the token is printed in the error output:
open https://app.usefloat.xyz/link?token=<token>
Clear the local config and re-link:
rm ~/.float/config.json
npx @usefloat/cli@latest init
USDC deposits can take 30–60 seconds to appear on-chain. Wait, then re-check:
npx @usefloat/cli@latest status

cat ~/.float/config.json

​
Quick reference

TaskCommand
Check Float statusnpx @usefloat/cli@latest status
Re-link / reset agentrm ~/.float/config.json && npx @usefloat/cli@latest init
List MCP tools in Claude Codeclaude mcp list
Update Float MCPnpx -y @usefloat/mcp@latest
View local Float configcat ~/.float/config.json
Load USDCopen https://app.usefloat.xyz/fund