@floelabs/mcp-server

Floe over MCP — know what every AI call really costs. Floe costs each call the moment

it ends across every vendor — telephony, STT, LLM, TTS, tools — on one ledger, ties the spend

to the client and campaign, and shows your margin per contract, so you can bill your own

customers off those actuals. This server puts that layer in your MCP client: give Claude

Desktop, Claude Code, Cursor, CrewAI, or any MCP client one key for every voice tool and model

a voice agent uses — STT, TTS, LLM, telephony — plus 2,000+ vendor API services, with

budgets the agent can reason about. Walletless. No crypto required.

Website · Docs · Dashboard · 𝕏 @FloeLabs

80 tools covering the full agent lifecycle — create agents, mint/rotate keys, set budgets, estimate costs, and execute x402 payments — with transport-aware auth (remote HTTP uses a Bearer token; local stdio reads `FLOE_API_KEY` from the env) and a keyless tier (`get_markets`, `check_x402_url`, `search_floe_docs` work with no key at all).

> Start free. A $3 Welcome Credit (300 API credits) on signup — no card, no wallet.

> Get an agent key →

Start building with Floe

One key for your agent's whole vendor bill — LLM, voice, telephony, search, data — metered per call and budget-capped. Let your coding agent set it up, or wire it yourself:

New accounts get a $3 Welcome Credit (300 API credits) — no card. Set up with your AI tools → · Get a key →

What makes this different

Most payment tools let an agent *spend*. Floe lets an agent **reason about spend

before it commits** — and stops it before it overruns.

• Agent-awareness tools — `get_credit_remaining`, `estimate_x402_cost`,

`get_loan_state`: your agent asks "do I have budget? is this call worth it?"

*before* paying, not after.

• Context-aware budgets — set a session spend cap; the agent tapers as it

nears the limit and replans to finish on budget.

• The Floe agent skill (Floe-Labs/agent-skills) — the playbook that

turns those tools into deliberate spending behavior. Jump to it ↓

• Server-side enforcement — the soft signal is the skill; the hard ceiling

is the on-chain spend cap + merchant allowlist. The agent cannot overspend

regardless of what it decides.

Quick start (remote, recommended)

One-liner installs:

# Universal (any MCP-aware client)
npx -y add-mcp https://mcp.floelabs.xyz/mcp

# Claude Code
claude mcp add --transport http floe https://mcp.floelabs.xyz/mcp --header "Authorization: Bearer YOUR_FLOE_KEY"

# Codex (reads the key from $FLOE_API_KEY at connect time)
codex mcp add floe --url https://mcp.floelabs.xyz/mcp --bearer-token-env-var FLOE_API_KEY

Or by JSON config:

{ "mcpServers": { "floe": {
  "url": "https://mcp.floelabs.xyz/mcp",
  "headers": { "Authorization": "Bearer floe_YOUR_AGENT_KEY" }
} } }

Get your agent key: dashboard → Create agent → copy the `floe_` key

(shown once). Or from the CLI: `npx @floelabs/cli init` — paste your dashboard developer key and it

creates (or selects) the agent and mints the key for you. No key yet? The server still works —

see Keyless tier.

Scope params — narrow what a session can do straight from the URL:

https://mcp.floelabs.xyz/mcp?read_only=true          # only non-mutating tools
https://mcp.floelabs.xyz/mcp?features=spend,pricing  # only the named capability groups

Capability groups: `lending`, `spend`, `pricing`, `lifecycle`, `observability`, `payments`, `webhooks`, `actuals`, `docs`.

Both params combine. The Floe agent skill's decision loop needs `spend,pricing`.

→ Local stdio, global install, and key taxonomy below

Tools at a glance

Full per-tool reference is in Tools (80) below.

Tested clients

Install options

Option 1 (remote) is in Quick start above. For local runs:

Local via npx

Run the server locally. It proxies all requests to the Floe API.

FLOE_API_KEY=floe_YOUR_AGENT_KEY npx -y @floelabs/mcp-server --stdio

Claude Desktop config:

{
  "mcpServers": {
    "floe": {
      "command": "npx",
      "args": ["-y", "@floelabs/mcp-server", "--stdio"],
      "env": {
        "FLOE_API_KEY": "floe_YOUR_AGENT_KEY"
      }
    }
  }
}

Cursor config (`.cursor/mcp.json`):

{
  "mcpServers": {
    "floe": {
      "command": "npx",
      "args": ["-y", "@floelabs/mcp-server", "--stdio"],
      "env": {
        "FLOE_API_KEY": "floe_YOUR_AGENT_KEY"
      }
    }
  }
}

Install globally

npm install -g @floelabs/mcp-server
FLOE_API_KEY=floe_YOUR_AGENT_KEY floe-mcp --stdio

Transport selection

`--stdio` and `--http` are explicit overrides. With neither flag, the server picks by

what stdin is: a pipe (an MCP client spawning it) → stdio; a terminal or a

service manager's `/dev/null` → HTTP on `127.0.0.1:3100`. So a bare `command: npx`

config now works — but keep `--stdio` in configs anyway so behavior never depends on

how the client wires stdio. On startup failure the process logs `[floe-mcp] Fatal:`

to stderr and exits with code 1; in stdio mode all logging goes to stderr, never

stdout (which carries the MCP protocol).

Auth model

Auth source depends on transport:

Keyless tier

The server starts (and the hosted endpoint answers) without any key. Keyless

sessions get exactly three tools with live results: `get_markets`,

`check_x402_url`, and `search_floe_docs` — enough to vet a vendor, price a call,

and learn the API before signup. Every other tool returns a structured error:

{ "error": "AUTH_REQUIRED", "status": 401,
  "message": "…Requires an agent key (floe_...).",
  "next": "Get a developer key at https://dev-dashboard.floelabs.xyz, then mint agent keys with create_agent_key. …" }

Tool errors always carry the backend's HTTP `status` (so agents can distinguish

401/403/404/429), and 401/403 include a remediation hint that distinguishes

missing key from wrong key type.

Which key to use

Two key formats unlock different surfaces — every tool description states which

one it needs:

Typical bootstrap: connect with the developer key → `create_agent` →

`create_agent_key` → reconnect (or open a second MCP session) with the minted

agent key to spend.

Get an agent key:

1. Go to dev-dashboard.floelabs.xyz

2. Connect your wallet and Create an agent (name + borrow limit + max rate)

3. Copy the `floe_` key shown at the end of the wizard — it is revealed once

You can also mint one from the CLI:

# Platform CLI — interactive: paste your developer key, create or select an
# agent, and the minted agent key lands in your OS keychain
# (manage agent keys later with `floe keys list|create|rotate|revoke`,
#  developer keys with `floe devkeys`)
npx @floelabs/cli init

# SDK-level alternatives:
# TypeScript SDK
npx floe-agent register --name my-agent --borrow-limit 10000

# Python SDK
floe-agent register --name my-agent --borrow-limit 10000

The platform CLI and this MCP server cover the same API surface. `@floelabs/cli` is the

full platform from a terminal — agents, keys, budgets, policies, billing, funds, phone,

metered calls — with `--json` on every command and stable exit codes for scripts and CI.

MCP remains the richer in-context integration: tools your agent discovers, reasons over,

and calls mid-session without shelling out.

Get a developer key (unlocks the lifecycle tools — `create_agent`, key minting, budgets, funding, webhooks — and multi-tenant visibility across all your agents):

1. Go to dev-dashboard.floelabs.xyz/keys

2. Click Create Key, label it, pick `read` or `read_write` permissions

3. Copy the `floe_live_` key shown once

Developer keys span the whole developer account and have a separate rate limit (100 req/min). Agent-runtime tools (`get_credit_remaining`, `get_spend_limit`, `x402_pay`, etc) return 401 with a developer key because the caller is the developer, not a single agent — the error's `next` hint says so and points at `create_agent_key`. See the API Keys docs for the full taxonomy.

> Fund with fiat: You can fund your wallet with USDC via Coinbase — credit card, bank transfer, Apple Pay, Google Pay — directly from the dashboard. No crypto on-ramp needed.

Multiple agents

One Floe developer can own many agents. To run several MCP sessions side by side (e.g. a research agent and a trading agent), mint one key per agent and configure each MCP client entry with its own key:

{
  "mcpServers": {
    "floe-research": {
      "url": "https://mcp.floelabs.xyz/mcp",
      "headers": { "Authorization": "Bearer floe_KEY_FOR_RESEARCH_AGENT" }
    },
    "floe-trading": {
      "url": "https://mcp.floelabs.xyz/mcp",
      "headers": { "Authorization": "Bearer floe_KEY_FOR_TRADING_AGENT" }
    }
  }
}

Each session is scoped to one agent — credit lines, spend limits, and webhooks stay isolated.

Environment Variables

Tools (80)

Below the tools are listed by request type. The summary is in Tools at a glance above.

Every description also names the key it needs: agent key (`floe_...`), developer key

(`floe_live_...`), any key, or none. The feature-group tag in each heading is what

`?features=` filters on.

Payment execution (`payments`, `pricing`) ⭐

The reason the rest exists: estimate → forecast → pay. `x402_pay` needs an agent key; `check_x402_url` is keyless.

Agent lifecycle (`lifecycle`) — developer key

Bootstrap and manage the fleet without touching the dashboard.

Funding & observability (`observability`) — developer key

Webhooks (`webhooks`) — developer key

Vendor actuals (`actuals`) — developer key

What your own vendors charged you (FLO-746), reconciled against those vendors' billing records — not what Floe charged you. Every cost carries a status, and a status is a claim:

`costRaw` is `null` for `pending` and `manual` — report units, never a zero. `exact` and `period-rate` are returned as separate subtotals and must never be added into one number.

When a cost arrives: some legs can be costed the moment a call ends, others only on the vendor's next-day batch — so a recent leg reads `pending`, which is the steady state, not a defect.

Coverage reads low on voice-heavy accounts at launch — a property of what vendors publish, not your setup. Close the gap via the invoice lane.

Gating: the four reads need the Pro feature `attribution_reports`; the two connection tools need the Agency feature `vendor_connections` (and admin/owner for `verify_vendor_connection`).

Not exposed over MCP, on purpose. Invoice upload is a binary PUT to a signed storage URL — no agent has a file to send. Footing an invoice writes `invoiced` stamps against a vendor's invoice and is not undone by re-running, so that irreversible finance action keeps a human in the loop. Resolving a finding is a human verdict — the API refuses the machine's own `auto_cleared` for exactly that reason. Creating a connection writes a sealed credential, and credentials never travel through a tool call. All four live in the dashboard and in `floe actuals`.

Docs (`docs`) — keyless

Read tools (`lending`)

Write tools (`lending`, return unsigned transactions)

Analysis tools (`lending`)

Utility tools (`lending`)

Agent-awareness tools (`spend`) ⭐

Lets an agent answer "do I have credit?", "is this call worth it?", and "where am I in the loan lifecycle?" before committing capital. All require an agent API key (`floe_*`). The calling identity is taken from the Bearer header in HTTP mode, or from `FLOE_API_KEY` in stdio mode.

Merchant-allowlist tools (`spend`)

Opt-in, default-deny restriction on which destinations the agent may pay. An allowlist entry is an ordinary capped policy row that doubles as "allowed AND capped". Default mode `off` = allow any vendor (zero onboarding friction). All require an agent API key (`floe_*`).

Inference gateway tools (`pricing`)

Budget-awareness skill

Floe's agent skills live in their own repo: **Floe-Labs/agent-skills**.

The `floe` skill is the *playbook* that turns the MCP tools above into deliberate spending behavior: read budget status before paying, taper as it nears the tightest cap, replan to finish the task on budget, and stop before the ceiling. It reads status from the existing `get_credit_remaining`, `get_spend_limit`, `estimate_x402_cost`, and `get_loan_state` tools, plus the `X-Floe-Budget-Advisory` header the Floe x402 proxy stamps on paid responses — no new tool or backend required.

> Soft signal, not the guardrail. The skill helps a cooperative agent spend wisely. The real ceiling is enforced server-side — the on-chain credit line, the session spend cap, and (if configured) the merchant allowlist refuse calls past the limit regardless of what the agent decides.

Install:

npx skills add floe-labs/agent-skills          # skills.sh CLI
# or manually:
git clone https://github.com/floe-labs/agent-skills
cp -r agent-skills/skills/floe ~/.claude/skills/   # or .claude/skills/ per-project

Transaction Flow

All write tools return unsigned transactions — the server never holds private keys.

1. Call a write tool (e.g., create_counter_intent)
   → Returns { transactions: [...], summary, warnings, expiresAt }

2. (Optional) Call simulate_transaction to dry-run

3. Sign each transaction locally with your wallet

4. Call broadcast_transaction with the signed hex
   → Returns { transactionHash, status, blockNumber }

Example: Get a USDC Credit Line

Agent: "I need 9,950 USDC working capital"

1. get_open_lend_intents → browse USDC/USDC offers
2. create_counter_intent(offer_hash, wallet) → unsigned txs
3. simulate_transaction(from, to, data) → { success: true, gasEstimate }
4. Sign locally → signed hex
5. broadcast_transaction(signed_hex) → confirmed

Signing with viem

import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const wallet = createWalletClient({
  account: privateKeyToAccount(PRIVATE_KEY),
  chain: base,
  transport: http(),
});

// Sign and send each transaction in order
for (const { transaction: tx } of response.transactions) {
  const hash = await wallet.sendTransaction({
    to: tx.to,
    data: tx.data,
    value: BigInt(tx.value),
  });
  // Wait for confirmation before next step
}

Programmatic Usage

MCP Client SDK

import { Client } from "@modelcontextprotocol/sdk/client";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "my-agent" });
await client.connect(new StreamableHTTPClientTransport(
  new URL("https://mcp.floelabs.xyz/mcp"),
  { requestInit: { headers: { "Authorization": "Bearer floe_..." } } }
));

const markets = await client.callTool("get_markets", {});
const counter = await client.callTool("create_counter_intent", {
  offer_hash: "0x...",
  wallet_address: "0x...",
});

LangChain / LangGraph

from langchain_mcp_adapters import MultiServerMCPClient

async with MultiServerMCPClient({
    "floe": {"url": "https://mcp.floelabs.xyz/mcp", "headers": {"Authorization": "Bearer floe_..."}}
}) as client:
    tools = client.get_tools()
    # Use tools in your agent

CrewAI

CrewAI agents can consume the Floe MCP tools via `langchain-mcp-adapters`. A runnable crew is available in floe-cookbook/crewai-demo.

Architecture

Your Agent → MCP Server → credit-api.floelabs.xyz → Envio Indexer / Base RPC
                ↑                    ↑
           This package         Private backend
          (open source)        (holds secrets)

The MCP server is a thin HTTP client. All protocol logic, indexer queries, and RPC calls happen in the private Floe API backend. This package contains only tool definitions and `fetch()` calls.

Lending protocol (advanced)

Floe is the spend layer for AI agents — one key that pays any vendor API under programmable budgets (everything above). It also exposes an advanced, crypto-native intent-based lending layer on Base, for agents that want working capital against deposits:

1. Primary market (USDC/USDC): Deposit USDC as collateral, borrow up to 99.5% as a credit line. No price-volatility risk — same-token market.

2. Volatile markets: Also supports WETH and cbBTC collateral for crypto-native use cases.

3. Solvers automatically match compatible intent pairs on-chain.

4. Loans are created with matched terms, collateral locked in per-loan isolated escrow.

5. Gas-free — Floe sponsors all transaction costs.

6. Fixed rates — no variable-rate surprises.

Key concepts:

• Intent: An on-chain offer to lend or borrow
• Counter-Intent: An intent created to match an existing offer
• Health Factor: Ratio of collateral value to debt — below threshold triggers liquidation
• LTV (Loan-to-Value): Borrower's debt as % of collateral value

Contract Addresses (Base Mainnet)

Links

• Website
• Dashboard
• Documentation
• Platform CLI (`@floelabs/cli`)
• TypeScript SDK (`floe-agent`)
• Python SDK (`floe-agentkit-actions`)
• End-to-end examples

License

MIT