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

Learn how to configure Claude Desktop to safely query multi-chain DeFi data, track yield opportunities, and execute trades using the Model Context Protocol.

TLDR: FarmDash publishes a public Agent Hub, OpenAPI contract, llms.txt, and MCP capability metadata for DeFi-agent integrations. A public stdio package or public source checkout for Claude Desktop is not currently advertised; use the REST/OpenAPI surface for supported integrations. Read /api/v1/agent/status first: wallet-affecting capabilities remain unavailable unless their runtime prerequisites and authorization gates are satisfied.

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 documents FarmDash's public MCP capability contract and REST/OpenAPI integration surface for multi-chain yield discovery, Sybil risk audits, and capability-gated spot/futures workflows with explicit signing or bounded-delegation boundaries.

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. Public Integration Status

FarmDash does not currently advertise a public npm package or public source checkout for the stdio server. Do not use unverified package names or repository links as an installation method.

Supported Path: REST / OpenAPI

Use the FarmDash Agent Hub and the canonical OpenAPI specification to generate a typed client or add schema-validated HTTP tools to your agent. The public MCP manifest remains useful for capability discovery, but is not a public Claude Desktop install instruction.

Scout access is available for limited public reads. When a paid capability returns HTTP 402, inspect the response-specific x402 payment requirements; do not move value merely to test an integration.

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.

Integration Aspect	Model Context Protocol (MCP)	TypeScript SDK (`@farmdash/agent-kit`)	REST API (`/api/v1/agent`)
Integration Pattern	Stdio/JSON-RPC proxy linked directly to a LLM client runtime.	ESM/CommonJS library imported into a Node.js process.	Direct HTTP GET/POST endpoints.
Primary Target Audience	Desktop LLMs (Claude Desktop, Cursor, Cline) acting as virtual analysts.	Standalone custom agents (e.g., Eliza frameworks, custom scripts).	Multi-language backend pipelines (Python, Rust, Go).
Developer Overhead	Low. The client reads tool schemas, while the operator still configures the source-built server, credentials, and capability checks.	Medium. Requires importing types, calling methods, and writing wrappers.	High. Requires manual HTTP routing, type definitions, and retry logic.
Signing Authority	User-local signing or a separately configured bounded delegation, depending on the route.	Caller-managed; the SDK does not create authority.	Caller-managed; the API validates the route-specific signature or delegation contract.
Execution Safety Gates	The server exposes the route lifecycle, but clients must read status, review the quote, and satisfy every policy/simulation/authorization gate.	The developer coordinates status, policy, simulation, and signing.	Direct callers must follow the same status, simulation, signing, and typed-error contracts.
Rate Limit Management	Survives overages via detailed `x402` prompt responses.	Surfaces rate limits via structured exception metadata.	Standard `429 Too Many Requests` or `402 Payment Required` status codes.

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

FarmDash does not request seed phrases or raw wallet private keys. Compatibility swap routes process actions as Intents; separately configured provider or venue delegations remain governed by their explicit bounds and controls.

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?

For the compatibility swap route, the server queries liquidity routers (for example, 0x and Li.Fi) to construct EVM calldata. It returns the payload for review after a fresh simulation and validates the corresponding EIP-191 authorization. FarmDash does not broadcast that returned transaction; the customer-controlled wallet or execution client decides whether to sign and submit it. Other venue-backed routes have their own status and delegation requirements.

Can I run the FarmDash MCP server on Windows?

FarmDash does not currently advertise a public stdio package or source checkout, so there is no supported public Claude Desktop path configuration. Use the public OpenAPI contract for supported Windows, browser, server, and agent integrations, and check the Agent Hub for future distribution updates.

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 x402 payment routing instructions. To unlock higher limits, configure a Pioneer key (FARMDASH_API_KEY) or pay the quoted request price (0.01 USDC for the default overage) from your connected wallet.

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

FarmDash does not request or parse seed phrases or raw wallet private-key parameters through its public integration surface. Compatibility swap payloads are signed outside FarmDash. If you separately configure an exchange API wallet, MPC provider, or another delegated venue, review that provider's custody model, limits, revocation path, and live FarmDash capability status before enabling it.

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.