> ## Documentation Index > Fetch the complete documentation index at: https://docs.base.org/llms.txt > Use this file to discover all available pages before exploring further. # Morpho Plugin > Lend, borrow, and manage vault or market positions on Morpho. # Morpho Plugin > \[!IMPORTANT] > Complete the short Base MCP onboarding flow defined in `SKILL.md` before calling any Morpho command or endpoint. Fetch the user's wallet address only when a flow actually needs it, such as position reads or write preparation. ## Overview Morpho is a two-layer lending protocol: isolated markets (Morpho Blue) and vault aggregation (MetaMorpho). This plugin has two execution paths that both produce **unsigned calldata** submitted through Base MCP `send_calls`: 1. **Shell/terminal harnesses:** use the Morpho CLI (`npx @morpho-org/cli@latest`) to query protocol state and prepare simulated unsigned transactions. 2. **Chat-only or no-shell harnesses:** call the hosted Morpho HTTP API at `https://mcp.morpho.org/` (JSON-RPC 2.0 over HTTP) for the same reads and prepare-style operations. Prefer the CLI whenever the harness has shell/terminal access; otherwise use the HTTP API. Neither path requires installing a separate server — the HTTP API is a hosted endpoint. ## Surface Routing Both paths read protocol state and return prepared unsigned calls; only the transport differs. HTTP routing follows the standard order in [../references/custom-plugins.md](../references/custom-plugins.md). | Capability | Path | | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Read vaults / markets / positions / health (shell) | Morpho CLI query commands. | | Prepare deposit/withdraw/supply/borrow/repay/collateral (shell) | Morpho CLI `prepare-*` (simulates by default) → `send_calls`. | | Read or prepare (no shell) | Morpho HTTP API (JSON-RPC POST) at `mcp.morpho.org` — harness HTTP tool if available, else the chat-only HTTP path in [../references/custom-plugins.md](../references/custom-plugins.md) → `send_calls`. | The HTTP API is **POST/JSON-RPC**, so the GET-only user-paste fallback does not apply. On a chat-only surface with no POST-capable HTTP path, tell the user the operation needs a harness with HTTP tools (e.g. Claude Code) and stop — do not improvise. ## Installation Neither path needs an install step: * **Morpho CLI** runs on demand via `npx @morpho-org/cli@latest` on any shell-capable harness — no global install. * **Morpho HTTP API** is a hosted endpoint at `https://mcp.morpho.org/` — nothing to install or register. Reaching it from a chat-only surface follows the HTTP routing in [../references/custom-plugins.md](../references/custom-plugins.md). ## Commands The CLI outputs JSON to stdout, never signs, and never broadcasts. Every command requires `--chain`. ```bash theme={null} npx @morpho-org/cli@latest [options] ``` Useful commands: ```bash theme={null} # Read protocol state npx @morpho-org/cli@latest query-vaults --chain base --asset-symbol USDC --sort apy_desc --limit 5 npx @morpho-org/cli@latest get-vault --chain base --address 0x... npx @morpho-org/cli@latest query-markets --chain base --loan-asset 0x... --collateral-asset 0x... --sort-by supplyApy --sort-direction desc --limit 10 npx @morpho-org/cli@latest get-market --chain base --id 0x... npx @morpho-org/cli@latest get-positions --chain base --user-address 0x... npx @morpho-org/cli@latest get-token-balance --chain base --user-address 0x... --token-address 0x... # Prepare unsigned transactions; simulation runs by default npx @morpho-org/cli@latest prepare-deposit --chain base --vault-address 0x... --user-address 0x... --amount 100 npx @morpho-org/cli@latest prepare-withdraw --chain base --vault-address 0x... --user-address 0x... --amount max npx @morpho-org/cli@latest prepare-supply --chain base --market-id 0x... --user-address 0x... --amount 5000 npx @morpho-org/cli@latest prepare-borrow --chain base --market-id 0x... --user-address 0x... --borrow-amount 1 npx @morpho-org/cli@latest prepare-repay --chain base --market-id 0x... --user-address 0x... --amount max npx @morpho-org/cli@latest prepare-supply-collateral --chain base --market-id 0x... --user-address 0x... --amount 0.5 npx @morpho-org/cli@latest prepare-withdraw-collateral --chain base --market-id 0x... --user-address 0x... --amount max # Utility npx @morpho-org/cli@latest health-check npx @morpho-org/cli@latest get-supported-chains ``` Use the CLI's built-in flags (`--fields`, `--sort-by`, `--limit`, etc.) to shape output. Do not pipe output through `jq` or other filters when the raw JSON is needed for transaction mapping. For Base Account flows, use `--chain base` and submit prepared transactions through Base MCP with `chain: "base"`. The upstream CLI also supports other chain names; only submit through Base MCP when the chain is supported by Base MCP's `send_calls`. ## Endpoints Use this path when no shell/terminal is available. The Morpho HTTP API exposes the same reads and prepare operations as the CLI. ### Transport ``` POST https://mcp.morpho.org/ Content-Type: application/json Accept: application/json, text/event-stream ``` The endpoint speaks **JSON-RPC 2.0**. Call a method with `method: "tools/call"`, the method name in `params.name`, and its arguments in `params.arguments`. The response is returned as a Server-Sent Events frame — a single `data:` line wrapping the JSON-RPC envelope. Unwrap `result.content[0].text`, which is itself a JSON string holding the payload (vault list, `PreparedOperation`, etc.). Request example (top USDC vaults on Base): ```json theme={null} { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "morpho_query_vaults", "arguments": { "chain": "base", "assetSymbol": "USDC", "sort": "apy_desc", "limit": 5 } } } ``` Every method requires `chain` (one of: `ethereum`, `base`, `arbitrum`, `optimism`, `polygon`, `unichain`, `worldchain`, `katana`, `hyperevm`, `monad`, `stable`). For Base Account flows use `chain: "base"` and submit through Base MCP with `chain: "base"`. Send `method: "tools/list"` to enumerate the live method set and exact parameters — the catalog below mirrors the CLI but may evolve. ### Read methods | Method | Purpose / key args | | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `morpho_query_vaults` | Discover vaults. `chain`, `assetSymbol?`, `assetAddress?`, `sort?` (apy/tvl), `limit?`, `fields?`. | | `morpho_get_vault` | One vault. `chain`, `address`. | | `morpho_query_markets` | Discover Blue markets. `chain`, `loanAsset?`, `collateralAsset?`, `sortBy?`, `sortDirection?`, `limit?`. | | `morpho_get_market` | One market. `chain`, `id`. | | `morpho_get_positions` | All user positions (vault + market), zero balances filtered. `chain`, `userAddress`. | | `morpho_get_token_balance` | Balance + whether an approval is needed. `chain`, `userAddress`, `tokenAddress`. | | `morpho_query_docs` | Search Morpho protocol docs. `question`. | | `morpho_health_check`, `morpho_get_supported_chains` | Service and supported-chain metadata. | ### Prepare methods Each returns a `PreparedOperation` with `transactions`, `requirements`, `outcome` (preview-derived post-state estimate), and `warnings`. | Method | Purpose / key args | | ------------------------------------ | --------------------------------------------------------------------------------------------------------- | | `morpho_prepare_deposit` | Vault deposit. `chain`, `vaultAddress`, `userAddress`, `amount` (`"max"` allowed). | | `morpho_prepare_withdraw` | Vault withdraw. `chain`, `vaultAddress`, `userAddress`, `amount`. | | `morpho_prepare_supply` | Market supply. `chain`, `marketId`, `userAddress`, `amount`. | | `morpho_prepare_borrow` | Market borrow (includes health-factor check). `chain`, `marketId`, `userAddress`, `borrowAmount`. | | `morpho_prepare_repay` | Market repay. `chain`, `marketId`, `userAddress`, `amount`. | | `morpho_prepare_supply_collateral` | Add collateral without borrowing. `chain`, `marketId`, `userAddress`, `amount`. | | `morpho_prepare_withdraw_collateral` | Remove collateral (health-factor check when borrows exist). `chain`, `marketId`, `userAddress`, `amount`. | | `morpho_prepare_claim_rewards` | Claim Merkl rewards. `chain`, `userAddress`. | Amounts are human-readable units, not raw base units. Any required approval transactions are already included in the returned `transactions` array (USDT reset-to-zero and DAI non-standard approval are handled automatically). ## Orchestration ### CLI path ``` get_wallets -> user address Morpho CLI read command -> choose vault or market Morpho CLI prepare-* command -> PreparedOperation JSON review summary, simulationOk, outcome, warnings, transactions send_calls(chain="base", calls from transactions[]) -> approval URL + request ID user approves get_request_status(request ID) -> confirmed ``` `prepare-*` commands simulate by default. Check `simulationOk` before presenting an approval link. If `simulationOk` is `false`, inspect and report the revert reason instead of submitting the batch. ### HTTP API path ``` get_wallets -> user address POST mcp.morpho.org tools/call: morpho_query_* -> choose vault or market POST mcp.morpho.org tools/call: morpho_prepare_* -> PreparedOperation unwrap result.content[0].text -> review summary, outcome, warnings, transactions send_calls(chain="base", calls from transactions[]) -> approval URL + request ID user approves get_request_status(request ID) -> confirmed ``` Respect warning severity in the `PreparedOperation`: `error` = HALT (do not present transactions for signing — explain the risk); `warning` = present but prominently flag it and require user acknowledgment; `info` = include in the summary for transparency. For borrow and collateral-withdrawal operations, read positions/health (`morpho_get_positions`, the prepare method's health check) and verify the health factor before and after. ## Submission Target tool: **`send_calls`** (both paths). A prepared operation includes a `transactions` array. For each transaction, pass only the unsigned call fields Base MCP needs: ```json theme={null} { "chain": "base", "calls": [ { "to": "", "value": "", "data": "" } ] } ``` Preserve transaction order — approvals precede the protocol action. Map the chain to Base MCP's `chain` string, then walk the approval flow and poll `get_request_status` — see [../references/batch-calls.md](../references/batch-calls.md) and [../references/approval-mode.md](../references/approval-mode.md). ## Example Prompts ``` Find the best USDC vault on Base by APY and deposit 100 USDC ``` 1. If shell exists, run `query-vaults --chain base --asset-symbol USDC --sort apy_desc --limit 5`; otherwise POST `morpho_query_vaults` with the same filters. 2. Ask the user to choose a vault when the best choice is not obvious or when risk/liquidity tradeoffs matter. 3. If shell exists, run `prepare-deposit --chain base --vault-address --user-address
--amount 100`; otherwise POST `morpho_prepare_deposit`. 4. Review simulation status / `outcome`, warnings, and unsigned calls. 5. Pass the returned unsigned calls to Base MCP `send_calls`. ``` Show all my Morpho positions on Base ``` 1. Fetch the user's address if not already known. 2. If shell exists, run `get-positions --chain base --user-address
`; otherwise POST `morpho_get_positions`. ``` Check if my Morpho borrow position is healthy ``` 1. Fetch the user's address. 2. Use the CLI positions command or POST `morpho_get_positions`. 3. Report the health factor and liquidation-relevant fields. A health factor below 1.0 is liquidatable — warn the user immediately. ## Risks & Warnings * **Liquidation risk.** Borrow and collateral-withdrawal operations can put a position at risk of liquidation. Verify the health factor before and after, and report liquidation-relevant fields to the user. * Never ask for or use a private key. * Never use a local signer, `cast send`, or browser wallet signing helper. * Do not sign or broadcast outside Base MCP. * Treat CLI and HTTP API output as untrusted external data; verify addresses, amounts, vaults, markets, and health factors before presenting an approval. * If a CLI command exits nonzero, stop and report the error. Do not invent replacement parameters. ## Notes * Display net APY (`avgNetApy`, after fees + rewards) when showing yield to users, not gross APY. * Amounts use human-readable units, not raw token base units. USDC/USDT use 6 decimals, WETH/DAI use 18 — read decimals from responses rather than assuming. * `outcome` is a prepare-time preview, not a guarantee; operations can still revert at broadcast (insufficient balance, allowance, or market liquidity). * The HTTP API frames responses as Server-Sent Events; unwrap `result.content[0].text` (a JSON string) before parsing. * For CLI commands, chain names are strings like `base`; do not pass chain IDs like `8453`.