MCP Configuration - Fibrous Documentation

FibX includes a built-in Model Context Protocol (MCP) server that exposes DeFi operations as callable tools. AI editors like Cursor, Claude Desktop, Antigravity, and any MCP-compatible client can connect to FibX and execute trades, transfers, and DeFi operations through natural language.

Quick Start

npx fibx mcp-start

This starts an MCP server over stdio (standard input/output). The server speaks JSON-RPC 2.0 and is designed to be launched by an AI editor, not run manually.

How It Works

Your AI editor spawns npx fibx mcp-start as a subprocess.
The editor communicates with FibX over stdin/stdout using JSON-RPC 2.0 messages.
Wallet-dependent tools read the local session file. Run fibx auth login or fibx auth import before using those tools; public tools such as quotes and Aave market discovery do not need a session.
Transactional tools execute against live blockchains and carry the MCP destructiveHint annotation. A client may use that hint to request confirmation, depending on its behavior and configuration.

stderr is used for logging, while stdout is reserved for JSON-RPC protocol messages.

Editor Setup

Add the FibX MCP server to your AI editor. FibX uses stdio transport — the editor spawns npx fibx mcp-start and communicates over standard input/output.

Open MCP settings with Command + Shift + P and search for “Open MCP settings”. Create or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "fibx": {
      "command": "npx",
      "args": ["-y", "fibx", "mcp-start"]
    }
  }
}

Test by asking Cursor: “What tools do you have available?” — it should list the FibX MCP server.

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "fibx": {
      "command": "npx",
      "args": ["-y", "fibx", "mcp-start"]
    }
  }
}

Restart Claude Desktop after editing the config. Authenticate with fibx auth login or fibx auth import before using wallet-dependent tools.

Create or edit .vscode/mcp.json in your project:

{
  "mcpServers": {
    "fibx": {
      "command": "npx",
      "args": ["-y", "fibx", "mcp-start"]
    }
  }
}

Reload the window or restart VS Code to activate the MCP server.

Open the MCP configuration in Windsurf settings and add:

{
  "mcpServers": {
    "fibx": {
      "command": "npx",
      "args": ["-y", "fibx", "mcp-start"]
    }
  }
}

Add to ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "fibx": {
      "command": "npx",
      "args": ["-y", "fibx", "mcp-start"]
    }
  }
}

ChatGPT and other tools without MCP support cannot connect to FibX directly. Use one of these alternatives:

CLI: Run npx fibx@latest commands directly in your terminal.
Agent Skills: Install fibx-skills for AI agents that support the Agent Skills format.
MCP-capable editor: Use Cursor, Claude Desktop, VS Code, or Windsurf with the config above.

You must be authenticated before the MCP server can execute wallet operations. Use fibx auth login or fibx auth import to authenticate.

Available Tools

FibX exposes 11 tools. The reference below groups them by read-only, transactional, and utility behavior.

Read-Only

Tool	Description	Auth Required
`get_quote`	Get a swap price quote, exchange rate, and route info	No
`get_auth_status`	Check session and Fibrous API health	No
`get_tx_status`	Check transaction receipt and status	No
`get_aave_markets`	List Aave V3 reserves with APY, supply/borrow totals, and LTV	No
`get_balance`	Get native and ERC-20 token balances	Yes
`get_portfolio`	Get cross-chain portfolio and DeFi positions	Yes
`get_aave_status`	Get Aave V3 position health on Base	Yes

get_quote needs no wallet and no session. An agent can answer “what would 1 ETH get me in USDC?” before the user has authenticated at all — useful as a first interaction.

Transactional

These tools carry the MCP destructiveHint annotation. Clients may use the hint to request confirmation, but confirmation behavior is client-dependent. All three accept simulate=true; its behavior is specific to each tool.

Tool	Description
`swap_tokens`	Swap tokens via Fibrous aggregator with optimal routing
`send_tokens`	Send native or ERC-20 tokens to a recipient
`aave_action`	Supply, borrow, repay, or withdraw on Aave V3 (Base)

simulate=true returns a no-broadcast preview, but the available checks differ by tool. If a swap needs ERC-20 approval, the preview reports requiresApproval: true without submitting the approval or estimating swap gas. aave_action returns normalized request metadata without on-chain validation or a gas estimate. A preview does not guarantee that later execution will succeed.

Utility

Tool	Description
`config_action`	Set or view custom RPC URLs to avoid rate limits

Tool Details

get_quote

Get a swap quote without a wallet or session.

Parameter	Type	Required	Description
`amount`	string	Yes	Amount of the source token to quote
`from_token`	string	Yes	Source token symbol (e.g. `ETH`, `USDC`)
`to_token`	string	Yes	Target token symbol (e.g. `USDC`, `DAI`)
`chain`	string	No	`base`, `citrea`, `hyperevm`, or `monad`
`slippage`	number	No	Slippage tolerance in percent (default: `0.5`)

Output: Routed swaps return input, output, rate, slippage, router, and chain. Direct native/wrapped-native pairs return input, output, rate, operation (wrap or unwrap), and chain.

get_auth_status

Check whether FibX is authenticated and the Fibrous API is reachable.

Parameter	Type	Required	Description
`chain`	string	No	`base`, `citrea`, `hyperevm`, or `monad`

Output: Object with authenticated, walletAddress, sessionType, chain, fibrousStatus

get_balance

Fetch token balances for the active wallet. The native-token entry is returned even when its balance is zero; ERC-20 entries are limited to non-zero balances.

Parameter	Type	Required	Description
`chain`	string	No	`base`, `citrea`, `hyperevm`, or `monad`

Output: Object with wallet, chain, and balances (e.g. ETH, USDC with amounts)

get_portfolio

Get a consolidated portfolio across all supported chains, including USD-valued token holdings and DeFi positions.

Parameter	Type	Required	Description
none	n/a	n/a	No input required

Output: Object with total portfolio USD value, per-chain assets, and DeFi position summaries Example prompts: “Show me my portfolio” or “What’s my total net worth across all chains?“

swap_tokens

Execute a token swap through Fibrous. Handles routing and any required ERC-20 approval.

Parameter	Type	Required	Description
`amount`	string	Yes	Amount of the source token to swap
`from_token`	string	Yes	Source token symbol (e.g. `ETH`, `USDC`)
`to_token`	string	Yes	Target token symbol (e.g. `USDC`, `DAI`)
`chain`	string	No	`base`, `citrea`, `hyperevm`, or `monad`
`slippage`	number	No	Slippage tolerance in percent (default 0.5)
`simulate`	boolean	No	Return a no-broadcast preview; gas may be unavailable

Execution output: txHash, amountIn, amountOut, tokenIn, tokenOut, router, chain, and explorer when available. Preview output: Direct wrap/unwrap previews return success, mode, operation, amountIn, tokenIn, tokenOut, and chain. Routed previews also return amountOut, router, and requiresApproval; estimatedGas is included only when the swap can be estimated without first broadcasting an approval.

A live routed ERC-20 swap may confirm an approval transaction before estimating and submitting the swap. If the later swap step fails, that approval remains on-chain. simulate=true broadcasts neither transaction.

Example prompt: “Swap 0.1 ETH to USDC on Base”

send_tokens

Transfer native or ERC-20 tokens.

Parameter	Type	Required	Description
`amount`	string	Yes	Amount to send
`recipient`	string	Yes	Recipient address (0x-prefixed)
`token`	string	No	Token symbol (omit for native token)
`chain`	string	No	`base`, `citrea`, `hyperevm`, or `monad`
`simulate`	boolean	No	Preflight the transfer without submitting it

Execution output: txHash, amount, token, recipient, chain, and explorer when available. Preview output: Both paths return success, mode, amount, token, recipient, and chain. Native-token previews also return estimatedGas; ERC-20 previews validate the transfer contract call without a gas field. Example prompt: “Send 50 USDC to 0x1234…“

get_tx_status

Look up a transaction receipt by hash.

Parameter	Type	Required	Description
`hash`	string	Yes	Transaction hash (0x-prefixed)
`chain`	string	No	Must match the chain of the original transaction

Output: Object with hash, status, blockNumber, from, to, gasUsed, chain, and explorer when available.

get_aave_status

Get Aave V3 account health on Base.

Parameter	Type	Required	Description
none	n/a	n/a	No input required

Output: Object with wallet, healthFactor, totalCollateralUSD, totalDebtUSD, availableBorrowsUSD

get_aave_markets

List Aave V3 reserve markets on Base. No wallet or session is required.

Parameter	Type	Required	Description
none	n/a	n/a	No input required

Output: Object with chain, marketCount, and markets. Each market includes symbol, supplyAPY, borrowAPY, totalSupply, totalBorrow, ltv, and isFrozen.

aave_action

Execute an Aave V3 operation on Base. ETH supply and repay can auto-wrap, ETH withdraw can auto-unwrap, and borrowing the ETH market returns WETH. Use max only for full repay or withdraw.

Parameter	Type	Required	Description
`action`	string	Yes	`supply`, `borrow`, `repay`, or `withdraw`
`amount`	string	Yes	Amount; `max` is allowed only for repay/withdraw
`token`	string	Yes	Token symbol (`ETH`, `USDC`, `DAI`, etc.)
`simulate`	boolean	No	Return an action preview without submitting it; does not estimate gas

Execution output: action, amount, token, txHash, chain, and explorer when available. A repay with no remaining debt instead returns status and no transaction hash. Preview output: success, mode (PREVIEW (no TX sent)), action, amount, token, chain, and note. The note states that no on-chain validation, gas estimate, or transaction was performed.

Live wrap, approval, Aave, and unwrap steps are separate transactions, so an earlier step remains on-chain if a later one fails. For an ETH withdrawal, the output transaction hash identifies the Aave withdrawal transaction, not the separate unwrap transaction. With action: "withdraw", amount: "max", and token: "ETH", FibX unwraps the wallet’s entire post-withdraw WETH balance, including WETH held before the request.

Example prompts: “Supply 0.5 ETH to Aave” or “Repay max USDC on Aave”

config_action

Manage custom RPC URLs. Useful when encountering rate limits on public endpoints.

Parameter	Type	Required	Description
`action`	string	Yes	`set-rpc`, `get-rpc`, `reset-rpc`, or `list`
`chain`	string	Conditional	Required for `set-rpc` and `get-rpc`
`url`	string	Conditional	Required for `set-rpc` — full RPC endpoint

Output: Object with action, chain, url, or rpcUrls depending on the action Example prompts: “I’m getting rate limited on Base, set a custom RPC” or “Reset all RPCs to default”

Supported Chains

Chain	Native Token	Fibrous Network
Base	ETH	base
Citrea	cBTC	citrea
HyperEVM	HYPE	hyperevm
Monad	MON	monad

Environment Variables

Variable	Description
`FIBX_API_URL`	Custom fibx-server URL (for Privy wallet operations)

If using Privy authentication, ensure fibx-server is running and accessible before starting the MCP server.

Troubleshooting

Problem	Solution
Server will not start	Ensure Node.js 18+ is installed and `npx fibx --version` works
”Not authenticated” errors	Run `fibx auth login <email>` or `fibx auth import` before using wallet-dependent tools
Wallet operations fail	Ensure `fibx-server` is running when using Privy-managed wallets
Rate limit errors	Use `config_action` to set a custom RPC URL
Editor cannot connect	Verify the MCP config JSON syntax and restart the editor

​Quick Start

​How It Works

​Editor Setup

​Available Tools

​Read-Only

​Transactional

​Utility

​Tool Details

​get_quote

​get_auth_status

​get_balance

​get_portfolio

​swap_tokens

​send_tokens

​get_tx_status

​get_aave_status

​get_aave_markets

​aave_action

​config_action

​Supported Chains

​Environment Variables

​Troubleshooting

Quick Start

How It Works

Editor Setup

Available Tools

Read-Only

Transactional

Utility

Tool Details

get_quote

get_auth_status

get_balance

get_portfolio

swap_tokens

send_tokens

get_tx_status

get_aave_status

get_aave_markets

aave_action

config_action

Supported Chains

Environment Variables

Troubleshooting