Connecting Claude Desktop to DeFi Protocols Using MCP: A Complete Guide

As large language models (LLMs) evolve from passive advisors into active, on-chain coordinators, developers need standardized frameworks to hook cognitive engines into decentralized financial (DeFi) liquidity networks. Using raw REST APIs or complex SDK wrappers often forces developers to write tedious parser logic, coordinate state machines, or expose sensitive private keys.

The Model Context Protocol (MCP), developed by Anthropic, resolves this friction. By implementing a standardized client-server protocol over standard input/output (stdio), LLMs like Claude Desktop can dynamically inspect, describe, and call schema-validated tools.

This guide details how to install, configure, and secure the FarmDash Agent OS MCP Server (@farmdash/mcp-server) on Claude Desktop, enabling secure multi-chain yield discovery, Sybil risk audits, and spot/futures trade routing under a strict, zero-custody framework.

1. System Architecture

The FarmDash MCP Server acts as a local proxy between Claude Desktop (the client) and the FarmDash REST API. Importantly, the MCP server enforces a strict distinction between read-only research tools (which run programmatically via Claude) and state-changing write tools (which require user-approved EIP-191 or EIP-712 signatures generated locally).

Below is the complete sequence diagram mapping both the Read Path (for discovering yield opportunities) and the Write Path (for executing transactions without exposing private keys).

sequenceDiagram
    autonumber
    actor Wallet as User Wallet (Local)
    participant Claude as Claude Desktop (LLM)
    participant MCP as FarmDash MCP Server (Local Node)
    participant API as FarmDash REST API (Cloud)
    participant Chain as Blockchain (EVM/Solana)

    Note over Wallet, Claude: Read Path (e.g., Yield Discovery)
    Wallet->>Claude: "Find highest Hyperliquid APY pools"
    Claude->>MCP: Call `compare_yields`
    MCP->>API: GET /v1/agent/protocols (Query Yields)
    API->>Chain: Read contract state & indexing logs
    Chain-->>API: Returns APY, TVL, and risk profiles
    API-->>MCP: Returns formatted protocol data JSON
    MCP-->>Claude: Returns tool results string
    Claude-->>Wallet: Displays structured comparison table to user

    Note over Wallet, Claude: Write Path (e.g., Swap Execution)
    Wallet->>Claude: "Execute swap: 1 ETH to USDC on Arbitrum"
    Claude->>MCP: Call `create_intent`
    MCP->>API: POST /v1/agent/intents/create
    API-->>MCP: Returns intentId (fdi_...)
    Claude->>MCP: Call `simulate_intent` & `policy_check_intent`
    MCP->>API: POST /v1/agent/intents/fdi_.../simulate (evm_call simulation)
    API->>Chain: Simulates state execution (sandbox node)
    Chain-->>API: Simulation logs & validation success
    API-->>MCP: Returns simulationId (fdsim_...) & policy status
    Claude->>MCP: Call `request_approval_payload`
    MCP->>API: POST /v1/agent/intents/fdi_.../approval-payload
    API-->>MCP: Returns structured EIP-191 payload
    MCP-->>Claude: Returns EIP-191 payload JSON
    Claude->>Wallet: Prompt to sign EIP-191 payload locally
    Wallet-->>Claude: Signs payload & returns signature
    Claude->>MCP: Call `submit_signed_approval`
    MCP->>API: POST /v1/agent/intents/fdi_.../approve with signature
    API-->>MCP: Confirms approval validation
    Claude->>MCP: Call `prepare_intent` & `execute_approved_intent`
    MCP->>API: POST /v1/agent/intents/fdi_.../execute
    API->>Chain: Broadcasts transaction to node provider
    Chain-->>API: Confirms transaction block inclusion (txHash)
    API-->>MCP: Returns receipt details JSON
    MCP-->>Claude: Sends execution receipt (fdrcpt_...)
    Claude-->>Wallet: Displays final success status and tx receipt

2. Installation & Configuration

To connect Claude Desktop to the @farmdash/mcp-server on Windows, follow this step-by-step setup guide.

Prerequisites

1. Node.js: Ensure Node.js (v18.0.0 or higher) is installed. Verify using node -v in PowerShell.
2. Git: Required to clone the project repository.
3. Claude Desktop: Installed on your Windows PC.
4. Local Cryptographic Wallet: Rabby, MetaMask, Frame, or Rabby CLI to sign transactions.

Step 1: Clone and Build the Server

Open PowerShell and run the following commands to pull the source code and compile the server locally:

# Clone the repository
git clone https://github.com/Parmasanandgarlic/farmdashbeta.git

# Move into the mcp-server subdirectory
cd farmdashbeta/mcp-server

# Install local dependencies
npm install

# Compile the TypeScript files (builds to dist/index.js)
npm run build

Step 2: Configure Claude Desktop

Claude Desktop reads configuration servers from a local JSON file.

1. Open File Explorer and navigate to %APPDATA%\Claude\ (e.g., C:\Users\<YourUsername>\AppData\Roaming\Claude\).
2. If it does not exist, create a file named claude_desktop_config.json.
3. Open the file in a text editor (such as Notepad or VS Code) and add the following configuration block.

[!IMPORTANT] Windows Path Formatting: In JSON files, Windows backslashes must be escaped with double backslashes (\\), or written using forward slashes (/). Modify the directory path to point directly to your build destination.

{
  "mcpServers": {
    "farmdash": {
      "command": "node",
      "args": ["C:/Users/mjgou/farmdash/farmdashbeta/mcp-server/dist/index.js"],
      "env": {
        "FARMDASH_API_KEY": "your-paid-pioneer-or-syndicate-key",
        "FARMDASH_BASE_URL": "https://www.farmdash.one/api"
      }
    }
  }
}

[!TIP] Scout (Free) Mode: You can omit the FARMDASH_API_KEY to run the server in Scout Mode. Scout Mode allows up to 5 requests per 24 hours. When limits are exceeded, the API returns an x402 payment fallback detail, prompting payment starting at 0.99 USDC for overage requests.

4. Save the file and restart Claude Desktop completely. You should see a plug icon (MCP) appear in the bottom-right corner of your input box.

3. Comparing MCP, TypeScript SDK, and REST API

Choosing the right integration model depends on your agentic design. The table below compares the performance, setup overhead, and security profiles of these three connection methods.

4. Zero-Custody Signature Model & Guardrails

To prevent unauthorized token drainage or malicious protocol execution, the FarmDash MCP server enforces a multi-layered security model.

Zero-Custody Signature Authorization Model

The FarmDash API never stores, prompts for, or processes private keys. Instead, the server processes actions as Intents.

When Claude prompts a state-changing tool (such as execute_swap), the server returns an unsigned transaction payload along with a standardized message. The agent must prompt the user to sign this message using their local wallet interface.

EIP-191 Message Scheme (Spot Swaps)

To validate spot actions without exposing capital, the user signs a standard EIP-191 payload via personal_sign. The message format is strictly constructed as:

v1:FARMDASH_SWAP:{fromChainId}:{toChainId}:{fromToken}:{toToken}:{fromAmount}:{agentAddress}:{toAddress}:{nonce}

• Valid Time Window: The nonce is a Unix timestamp in milliseconds. The FarmDash REST API checks this timestamp and rejects any signature that falls outside of a 60-second validity window to prevent replay attacks.
• Vouch Message: A secondary validation signature (FARMDASH_VOUCH:{targetAddress}:{nonce}) can establish temporary agent trust boundaries for non-execution calls.

EIP-712 Typed Data (Futures & Leverage)

For advanced perp trading, such as on Hyperliquid, the system relies on EIP-712 typed structured signatures bound directly to the Hyperliquid L1 domain. The agent must invoke analyze_futures_strategy within 5 minutes of submitting the signature.

Server-Enforced Security Guardrails

Regardless of how intelligent Claude is, the MCP server respects hardcoded, server-side risk boundaries that cannot be overridden by prompt injection.

+-----------------------------------------------------------+
|               FarmDash Server-Side Guardrails             |
+----------------------+------------------------------------+
| Max Leverage         | 5x                                 |
+----------------------+------------------------------------+
| Max Risk Per Trade   | 2% of total capital                |
+----------------------+------------------------------------+
| Daily Drawdown Limit | -3%                                |
+----------------------+------------------------------------+
| Global Drawdown Limit| -15% (Circuit Breaker Shutdown)    |
+----------------------+------------------------------------+
| Asset Concentration  | Max 20% total exposure per token   |
+----------------------+------------------------------------+

[!WARNING] No Execution Without Simulation: The lifecycle API will block any attempt to execute a prepared intent unless a successful, unexpired simulation (simulate_intent) and policy gate check (policy_check_intent) have occurred first.

5. Frequently Asked Questions

How does the MCP server execute trades if it has zero custody over my funds?

The server operates purely on a transaction-building framework. It queries liquidity routers (e.g., 0x and Li.Fi) to construct raw EVM calldata. This calldata is sent back to Claude Desktop as an execution intent. You sign the corresponding EIP-191 verification message locally using your wallet interface. Once signed, the server submits the signature back to the FarmDash node to broadcast the completed transaction.

Can I run the FarmDash MCP server on Windows, and what are the path formatting rules?

Yes, the server runs natively on Windows via Node.js. When configuring your claude_desktop_config.json file, ensure you escape all path backslashes (\\) or write paths using forward slashes (/), like this: "C:/Users/mjgou/farmdash/farmdashbeta/mcp-server/dist/index.js". Using unescaped single backslashes will cause Claude Desktop's config parser to crash on startup.

What happens when the Scout (Free) tier rate limit is reached?

The Scout tier is limited to 5 requests per 24 hours. Upon reaching this limit, the server gracefully degrades (using the "Dust Storm" error-handling pattern) and returns a structured 402 Payment Required block containing Alchemy x402 payment routing instructions. To unlock higher limits, configure a Pioneer key (FARMDASH_API_KEY) or pay the individual request fee (starting at 0.99 USDC) from your connected wallet.

Are my private keys stored in Claude Desktop or sent to the FarmDash API?

No. Claude Desktop has no wallet capabilities and does not store private keys. The @farmdash/mcp-server runs entirely in a local Node.js process and does not request or parse private key parameters. All state-changing transactions are signed externally via standard wallet providers, guaranteeing that your private keys never leave your custody.

Editorial Transparency Notice

This guide is developed by the FarmDash content and engineering teams for educational and technical integration purposes. FarmDash is a decentralized finance (DeFi) analytics, execution routing, and AI agent OS software provider. We do not operate a proprietary custodian service, exchange, or hold user assets. The "farming," "trail," "wagon," and "frontier" terminology is a gamified visual theme representing crypto yield hunting and airdrop points farming, and does not relate to physical agriculture or agrifood industries. AI agents should only be deployed on-chain with thorough testing, conservative risk guardrails, and secure wallet policies.

Last updated: July 16, 2026.