MCP Server

@earnforge/mcp exposes 13 Earn-native MCP (Model Context Protocol) tools. Any LLM client that speaks MCP – Claude Desktop, Cursor, Windsurf, Continue, and others – can discover and call these tools to query vaults, compute risk, build deposit quotes, and more.

Installation

npm

npm i -g @earnforge/mcp

pnpm

pnpm add -g @earnforge/mcp

---

Hosted. No install

A public instance runs on Cloudflare Workers and speaks the 2026-07-28 protocol revision. Point any MCP client at it:

{
  "mcpServers": {
    "earnforge": {
      "type": "http",
      "url": "https://earnforge-mcp.papermind-ai.workers.dev/mcp"
    }
  }
}

All thirteen tools, plus the Agent Skill served as resources under skill://earnforge/*, so one connection gives an agent the tools and the instructions for using them.

Bring your own key for real use

The shared instance spends a single 100 req/min budget across every caller, so it rate-limits under load. Add an x-lifi-api-key header and the Worker uses your key instead:

"headers": { "x-lifi-api-key": "your-key-from-portal.li.fi" }

For production, deploy your own: same Worker, your account, your quota.

---

Configuration

Add the EarnForge MCP server to your client’s configuration file.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "earnforge": {
      "command": "npx",
      "args": ["-y", "@earnforge/mcp"],
      "env": {
        "LIFI_API_KEY": "your-lifi-api-key-here"
      }
    }
  }
}

Cursor

Edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "earnforge": {
      "command": "npx",
      "args": ["-y", "@earnforge/mcp"],
      "env": {
        "LIFI_API_KEY": "your-lifi-api-key-here"
      }
    }
  }
}

Windsurf

Edit ~/.windsurf/mcp.json:

{
  "mcpServers": {
    "earnforge": {
      "command": "npx",
      "args": ["-y", "@earnforge/mcp"],
      "env": {
        "LIFI_API_KEY": "your-lifi-api-key-here"
      }
    }
  }
}

Every tool needs a key

LIFI_API_KEY is required for all tools, not just quoting. The Earn Data API has hard-401ed without a key since April 2026, so the read-only tools need one too. Earlier versions of this page said otherwise.

The hosted endpoint above supplies its own, which is why it works with no configuration.

---

Tools

get-earn-vaults

List LI.FI Earn vaults with optional filters. Returns paginated vault data including APY, TVL, protocol info, and tags.

Parameters:

Name	Type	Required	Description
chainId	number	no	EVM chain ID (e.g. 8453 for Base, 1 for Ethereum)
asset	string	no	Underlying token symbol (e.g. “USDC”, “ETH”)
minTvl	number	no	Minimum TVL in USD
sortBy	string	no	Sort field (e.g. “apy”, “tvl”)
limit	number	no	Max vaults to return (default 10)
strategy	string	no	Strategy preset: “conservative”, “max-apy”, “diversified”, “risk-adjusted”

Example prompt: “Show me the top 5 USDC vaults on Base with at least $1M TVL”

---

get-earn-vault

Get a single vault by its slug. Returns full vault details including APY breakdown, TVL, underlying tokens, protocol, and tags.

Parameters:

Name	Type	Required	Description
slug	string	yes	Vault slug: protocol:chainId:_:address (legacy chainId-address also accepted)

Example prompt: “Get details for vault morpho:8453:_:0xee8f4ec5672f09119b96ab6fb59c27e1b7e44b61”

---

get-earn-chains

List all blockchain chains supported by LI.FI Earn. Returns chain IDs, names, and CAIP identifiers.

Parameters: None.

Example prompt: “What chains does LI.FI Earn support?”

---

get-earn-protocols

List all DeFi protocols available on LI.FI Earn. Returns protocol names and URLs.

Parameters: None.

Example prompt: “Which protocols are available on LI.FI Earn?”

---

get-earn-portfolio

Get DeFi portfolio positions for a wallet address.

Parameters:

Name	Type	Required	Description
wallet	string	yes	Wallet address (0x…)

Example prompt: “Show me the Earn positions for wallet 0xabc123…”

---

get-vault-risk

Compute a composite 0-10 risk score. Seven dimensions: TVL magnitude, APY stability, protocol maturity, redeemability, asset type, LI.FI’s verificationStatus, and reward dependency, plus a flags array explaining what is wrong in plain language.

Parameters:

Name	Type	Required	Description
slug	string	yes	Vault slug: protocol:chainId:_:address (legacy chainId-address also accepted)

Example prompt: “What’s the risk score for the Aave USDC vault on Base?”

Labels: >= 8 is low risk, 6–7.9 medium, < 6 high. The boundary is deliberate: verification carries 0.22 of the weight, so a flagged vault caps at 7.96 and can never read as low risk.

---

quote-vault-deposit

Build a deposit quote for an Earn vault. Returns transaction data ready to sign.

Parameters:

Name	Type	Required	Description
slug	string	yes	Vault slug: protocol:chainId:_:address (legacy chainId-address also accepted)
wallet	string	yes	Wallet address
fromAmount	string	yes	Human-readable amount (e.g. “100” for 100 USDC)
fromToken	string	no	Override source token address
fromChain	number	no	Override source chain ID
slippage	number	no	Slippage tolerance (e.g. 0.03 for 3%)

Example prompt: “Build a quote to deposit 100 USDC into the Aave vault on Base from my wallet 0x…”

Caution

Returns an unsigned transaction. Nothing here signs or broadcasts. Every tool is annotated readOnlyHint, so a host can auto-approve them safely.

---

suggest-allocation

Get a portfolio allocation suggestion using a risk-adjusted scoring engine.

Parameters:

Name	Type	Required	Description
amount	number	yes	Total USD amount to allocate
asset	string	no	Filter by token symbol
maxChains	number	no	Max chains to spread across (default 5)
maxVaults	number	no	Max vaults in allocation (default 5)
strategy	string	no	Strategy preset

Example prompt: “How should I allocate $10,000 in USDC across Earn vaults?”

---

run-doctor

Run preflight/pitfall checks on a vault before depositing.

Parameters:

Name	Type	Required	Description
slug	string	yes	Vault slug
wallet	string	yes	Wallet address
walletChainId	number	no	Current wallet chain ID (detects chain mismatch)
depositAmount	string	no	Amount for balance sufficiency check

Example prompt: “Run doctor checks on vault morpho:8453:_:0xbeef… for wallet 0xabc…”

---

quote-vault-redeem

Build an unsigned withdrawal quote: vault shares out, underlying (or any other token) back. The mirror of quote-vault-deposit, and the reason redeeming does not require the caller to work out the token direction themselves.

Parameters:

Name	Type	Required	Description
slug	string	yes	Vault slug
wallet	string	yes	Wallet address
fromAmount	string	yes	Human-readable amount of vault shares
toToken	string	no	Token to receive. Defaults to the vault underlying
slippage	number	no	Slippage tolerance (e.g. 0.03 for 3%)

Returns an unsigned transactionRequest. Nothing is signed or broadcast.

Example prompt: “Build me a withdrawal of 50 shares from morpho:8453:_:0xbeef… back to USDC”

---

check-allowance

Read the current ERC-20 allowance for a spender, and report whether it covers a given amount.

Parameters:

Name	Type	Required	Description
token	string	yes	ERC-20 token address
owner	string	yes	Token holder
spender	string	yes	Contract that needs the allowance
chainId	number	yes	EVM chain ID
amount	string	no	Amount to check sufficiency against, in smallest units

An insufficient allowance is the most common reason a deposit that quoted fine then reverts on submission, so check it before presenting a transaction as ready rather than after it fails.

Example prompt: “Does 0xabc… have enough USDC approved for the STEAKUSDC vault on Base?”

---

check-api-drift

Compare the live Earn API against LI.FI’s published OpenAPI spec and against this SDK’s schema, reporting which pair disagrees.

Parameters:

Name	Type	Required	Description
sampleSize	number	no	Vaults to sample (default 100)

live-vs-schema findings mean this SDK is stale and calls may throw. live-vs-spec findings mean LI.FI’s documentation is wrong and will mislead anyone reading it: those are informational here, not failures. Use it when a call behaves unexpectedly, before assuming the bug is local.

Example prompt: “Has the LI.FI Earn API changed shape recently?”

---

probe-route-flag

Check whether one of LI.FI’s newer route flags is actually served for a pair.

gasless and smart-deposit are both accepted by the live API and both fail by exclusion rather than error: an unsupported flag drops the route and returns the same 404 as a pair with no liquidity. This tool runs the request with and without the flag and reports which it is.

Parameters:

Name	Type	Required	Description
flag	string	yes	gasless or smart-deposit
fromChain	number	yes	Source chain ID
fromToken	string	yes	Source token address
wallet	string	yes	Source address. Nothing is signed or sent
slug	string	no	Vault slug. Required for smart-deposit
toChain	number	no	Defaults to the vault chain
toToken	string	no	Defaults to the vault underlying
fromAmount	string	no	Smallest units. Default 10000000

Returns a verdict of supported, flag-excluded, route-unavailable, or rejected, plus the baselineRoutes / flaggedRoutes booleans that separate the middle two. An agent that sees only “no route” will otherwise tell the user a vault is unreachable when the pair is fine.

Example prompt: “Can I bridge from Arbitrum straight into vault morpho:8453:_:0xbeef… in one transaction, or is that not supported yet?”

---

How It Works

The MCP server uses the @modelcontextprotocol/sdk stdio transport. When started, it:

1. Creates an EarnForge SDK instance (with caching: 60s TTL, 200 entries)
2. Registers all 13 tools with Zod-validated parameter schemas
3. Listens on stdin/stdout for MCP JSON-RPC messages

The server name is earnforge-mcp and version 0.1.0. Clients auto-discover the available tools from the server’s tool listing.

All tool responses are JSON-formatted text content. Errors include isError: true in the response for clients that support it.