MCP Server

@earnforge/mcp exposes 12 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 twelve 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…”

---

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 12 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.