@floelabs/mcp-server

The spend layer for AI agents, over MCP. Give Claude Desktop, Claude Code, Cursor, CrewAI, or any MCP client a single surface to pay 2,000+ vendor API services — with budgets the agent can reason about. Walletless. No crypto required.

Website · Docs · Dashboard · 𝕏

41 tools, transport-aware auth (remote HTTP uses a Bearer token; local stdio reads FLOE_API_KEY from the env).

Start free. $2 in API credit on signup — no card, no wallet. Get an agent 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-budget Claude Skill (ships in this repo) — 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.

Related MCP server: AgentPay

Quick start (remote, recommended)

{ "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_<hex> key (shown once). Or from the CLI: npx floe-agent register --name my-agent.

→ Local stdio, global install, and key taxonomy below

Tools at a glance

Full per-tool reference is in Tools (41) 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 @floelabs/mcp-server

Claude Desktop config:

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

Cursor config (.cursor/mcp.json):

{
  "mcpServers": {
    "floe": {
      "command": "npx",
      "args": ["@floelabs/mcp-server"],
      "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

Auth model

Auth source depends on transport:

Which key to use

Two key formats unlock different surfaces:

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_<64-hex> key shown at the end of the wizard — it is revealed once

You can also mint one from the CLI without visiting the dashboard:

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

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

Get a developer key (only if you need multi-tenant access 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_<base62> key shown once

Developer keys span the whole developer account and have a separate rate limit (100 req/min). Agent-awareness tools (get_credit_remaining, get_spend_limit, etc) return 401 with a developer key because the caller is the developer, not a single agent — use an agent key for those. 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 (41)

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

Read tools

Write tools (return unsigned transactions)

Analysis tools

Utility tools

Agent-awareness tools ⭐

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 (and as a fallback in HTTP mode when ALLOW_SHARED_KEY_FALLBACK=true).

Merchant-allowlist tools

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_*).

Roadmap tools (not yet shipped)

• get_credit_profile — read a portable ERC-8004 credit record (Preview)

• request_unsecured_credit — apply for receivables-backed credit (Preview)

• create_onramp_link — generate a one-shot fiat on-ramp URL for an agent operator (Roadmap)

Email hello@floelabs.xyz for early access to any of these.

Budget-awareness skill (floe-budget)

A portable Claude Skill ships with this repo at skills/floe-budget/. It makes any Claude-native agent (Claude Code, the Agent SDK, claude.ai, or any MCP client) spend its Floe credit deliberately: read budget status before paying, taper as it nears the tightest cap, replan to finish the task on budget, and stop before the ceiling.

The MCP tools above are the actions; the skill is the playbook. It reads budget 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 is 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.

Use it:

• Claude Code — copy the folder into your personal (or a repo's .claude/) skills directory; Claude discovers it automatically from the SKILL.md frontmatter.

  • From a cloned repo: cp -r skills/floe-budget ~/.claude/skills/

  • From an npm install: cp -r node_modules/@floelabs/mcp-server/skills/floe-budget ~/.claude/skills/

• claude.ai / Agent SDK — upload or register the floe-budget skill folder per the Agent Skills docs.

• Any MCP client — point the model at skills/floe-budget/SKILL.md as system/context guidance alongside the Floe MCP connection.

See skills/floe-budget/SKILL.md for the playbook and skills/floe-budget/reference.md for the X-Floe-Budget-Advisory field reference.

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.

Protocol overview

Floe is an intent-based lending protocol on Base, surfaced as the lending layer of the Financial OS:

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

• TypeScript SDK (floe-agent)

• Python SDK (floe-agentkit-actions)

• End-to-end examples

License

MIT