MCP Server

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI assistants (like Claude, Cursor, Windsurf, Antigravity) to interact with external tools. StarkFi runs as an MCP server, exposing every DeFi feature as a typed tool with Zod-validated schemas.

Prerequisites

Before using StarkFi MCP tools:

Node.js v18 or later
StarkFi Auth Server running (required for authentication and signing)
Authentication — run npx starkfi@latest auth login <email> and verify with the OTP before the MCP server can execute transactions

Important: The MCP server requires an active authenticated session. Always call get_auth_status first to verify the session is active before attempting any wallet operations.

Getting Started

1. Configure your AI client  →  See Setup
2. get_auth_status            →  Verify session is active
3. Read-only tools            →  Query balances, quotes, positions (safe, no confirmation needed)
4. Transactional tools        →  Execute swaps, sends, staking (requires user confirmation)

Tool Categories

Category	Count	Tools
Auth & Config	2	`get_auth_status`, `config_action`
Wallet	5	`get_tx_status`, `get_balance`, `deploy_account`, `send_tokens`, `get_portfolio`
Trade	5	`get_swap_quote`, `swap_tokens`, `get_multi_swap_quote`, `multi_swap`, `batch_execute`
Staking	8	`list_validators`, `list_pools`, `get_staking_info`, `get_stake_status`, `stake_tokens`, `unstake_tokens`, `claim_rewards`, `compound_rewards`
Lending	7	`list_lending_pools`, `get_lending_position`, `supply_assets`, `withdraw_assets`, `borrow_assets`, `repay_debt`, `close_position`

How It Works

StarkFi starts an MCP server via starkfi mcp-start
The server uses StdioServerTransport for communication
AI clients connect and discover all 27 tools with JSON schemas
The AI sends tool calls, StarkFi executes them on Starknet
Results are returned as structured JSON

All tools return consistent error responses with typed StarkfiError codes — see Error Handling.

Read-Only vs Transactional

	Read-Only	Transactional
Examples	`get_balance`, `get_swap_quote`, `list_validators`	`swap_tokens`, `send_tokens`, `stake_tokens`
Side effects	None — safe to call freely	Mutates blockchain state
User confirmation	Not needed	Always required before execution
Simulation	N/A	Set `simulate: true` to preview fees without executing

Agent Best Practices

Always authenticate first — call get_auth_status before any operation
Quote before executing — call get_swap_quote before swap_tokens, and get_multi_swap_quote before multi_swap
Use simulation — set simulate: true on any transactional tool to preview fees
Confirm with the user — never execute a transactional tool without explicit user confirmation
Check existing positions — use get_stake_status and get_lending_position before staking/lending to avoid duplicates

Starting the Server

starkfi mcp-start

Or configure it as an MCP server in your AI client's config — see Setup.

On this page