> ## Documentation Index
> Fetch the complete documentation index at: https://docs.legend.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Tools

> Complete reference for Legend MCP tools

# MCP Tools

These tools are available via the Legend MCP servers. Tools marked with **(local only)** are only available on the local MCP server (`legend-cli mcp serve`).

## Reference Data

### `list_networks`

List all supported blockchain networks.

**Parameters:** None

**Returns:** Array of `{name, chain_id, display_name}`. Use the `name` field (e.g. `"base"`, `"ethereum"`, `"arbitrum"`) as the `network` parameter in other tools.

***

### `list_assets`

List all supported tokens with decimals and network availability.

| Parameter | Type   | Required | Description                                |
| --------- | ------ | -------- | ------------------------------------------ |
| `network` | string | No       | Filter to assets available on this network |

**Returns:** Map of symbol → `{name, decimals, networks}`. Common decimals: USDC/USDT = 6, ETH/WETH = 18.

## Accounts

### `list_accounts`

List all sub-accounts under your Prime Account.

**Parameters:** None

**Returns:** Array of accounts with `account_id`, `signer_type`, wallet addresses, `created_at`. Call this first to discover account IDs.

***

### `get_account_info`

Get details for a specific account.

| Parameter    | Type   | Required | Description                   |
| ------------ | ------ | -------- | ----------------------------- |
| `account_id` | string | Yes      | Account ID (e.g. `"acc_xxx"`) |

**Returns:** Account details including `account_id`, `signer_type`, `ethereum_signer_address`, `legend_wallet_address`, `solana_wallet_address`.

## Portfolio

### `get_portfolio`

Get an account's current balances, token prices, yield positions, and rewards.

| Parameter    | Type   | Required | Description |
| ------------ | ------ | -------- | ----------- |
| `account_id` | string | Yes      | Account ID  |

**Returns:** Full folio data. Amounts use scientific notation:

* `"300.25e6"` = 300.25 USDC (6 decimals)
* `"1.5e18"` = 1.5 ETH (18 decimals)

**Key folio sections:**

* **balances** — token amounts per network per wallet (`balances/token/{network}/{symbol}/{wallet}`)
* **prices** — USD token prices (`prices/token/{symbol}`)
* **yield\_markets** — available yield with APY (`yield_markets/{protocol}/{network}/{address}/{asset}`)
* **rewards** — unclaimed protocol rewards

<Tip>
  **yield\_market key mapping:** The first path component maps to the plan `protocol` parameter: `comet` → `"compound"`, `aave` → `"aave"`, `morpho_vault` → `"morpho_vault"`. Use these exact values.
</Tip>

***

### `get_activities`

Get recent transaction history.

| Parameter    | Type    | Required | Description                       |
| ------------ | ------- | -------- | --------------------------------- |
| `account_id` | string  | Yes      | Account ID                        |
| `limit`      | integer | No       | Max results (default 20, max 100) |

**Returns:** Array of activities with `status` (`pending`, `completed`, `failed`), execution details, and transaction hashes.

## Plans

Plans are free previews — nothing executes until you sign and call `execute_plan`. Plans expire after **2 minutes**.

### `create_earn_plan`

Create a plan to earn yield on an asset.

| Parameter    | Type   | Required | Description                                    |
| ------------ | ------ | -------- | ---------------------------------------------- |
| `account_id` | string | Yes      | Account ID                                     |
| `amount`     | string | Yes      | Amount in smallest unit (`"1000000"` = 1 USDC) |
| `asset`      | string | Yes      | Asset symbol from yield\_market key            |
| `network`    | string | Yes      | Network from yield\_market key                 |
| `protocol`   | string | Yes      | `"compound"`, `"aave"`, or `"morpho_vault"`    |

**Returns:** `plan_id`, `digest` (for signing), `expires_at`, `steps` (action preview).

Legend handles cross-chain bridging automatically — just specify the target network.

***

### `create_swap_plan`

Create a plan to swap tokens.

| Parameter     | Type   | Required | Description                                           |
| ------------- | ------ | -------- | ----------------------------------------------------- |
| `account_id`  | string | Yes      | Account ID                                            |
| `sell_asset`  | string | Yes      | Asset to sell (e.g. `"USDC"`)                         |
| `buy_asset`   | string | Yes      | Asset to buy (e.g. `"WETH"`)                          |
| `network`     | string | Yes      | Network for the swap                                  |
| `sell_amount` | string | No       | Amount to sell (mutually exclusive with `buy_amount`) |
| `buy_amount`  | string | No       | Amount to buy (mutually exclusive with `sell_amount`) |

**Returns:** `plan_id`, `digest`, `expires_at`, `steps`.

## Execution

### `execute_plan`

Execute a previously created plan.

| Parameter    | Type   | Required | Description                           |
| ------------ | ------ | -------- | ------------------------------------- |
| `account_id` | string | Yes      | Account ID                            |
| `plan_id`    | string | Yes      | From a `create_*_plan` response       |
| `signature`  | string | Yes      | EIP-712 signature (`0x`-prefixed hex) |

**Returns:** `plan_id`, `activity_id`, `status`.

### How to Sign (remote MCP only)

When using the remote MCP server, the `create_*_plan` tools return a `digest` field. To get the signature:

**Using the CLI (Turnkey P256 accounts):**

```bash theme={null}
legend-cli sign 0xabc123...
# Output: 0xdef456...
```

**Using viem (EOA accounts):**

```typescript theme={null}
import { privateKeyToAccount } from "viem/accounts";
const signer = privateKeyToAccount(privateKey);
const signature = await signer.sign({ hash: digest });
```

<Warning>
  Plans expire after 2 minutes. Create, sign, and execute promptly.
</Warning>

## Local-Only Tools

These tools are only available on the local MCP server (`legend-cli mcp serve`). They leverage the P256 key stored on your machine.

### `login` (local only)

Authenticate via Google SSO. Opens a browser, completes the OAuth flow, and saves a 30-day JWT to your profile.

**Parameters:** None

**Returns:** Confirmation with profile name.

***

### `create_account` (local only)

Create a new sub-account with optional P256 key generation.

| Parameter         | Type    | Required | Description                                                        |
| ----------------- | ------- | -------- | ------------------------------------------------------------------ |
| `keygen`          | boolean | No       | Generate a P256 key and create a Turnkey account (default: `true`) |
| `use_file_key`    | boolean | No       | Use file-based key instead of macOS Keychain (default: `false`)    |
| `signer_type`     | string  | No       | `"eoa"` or `"turnkey_p256"` (when `keygen` is false)               |
| `ethereum_signer` | string  | No       | Ethereum address (for EOA accounts)                                |

**Returns:** Account details including `account_id`, `signer_type`, wallet addresses, and `turnkey_sub_org_id`.

With `keygen: true` (the default), the tool generates a P256 key in macOS Keychain, creates a Turnkey-backed account, and saves the key reference to your profile — all in one step.

***

### `sign_digest` (local only)

Sign an EIP-712 digest using the profile's P256 key via Turnkey.

| Parameter | Type   | Required | Description                      |
| --------- | ------ | -------- | -------------------------------- |
| `digest`  | string | Yes      | `0x`-prefixed hex digest to sign |

**Returns:** `{signature: "0x..."}` — the EIP-712 signature (132 hex chars).

***

### `plan_and_execute` (local only)

Create a plan, sign it with the local P256 key, and execute — all in one tool call. This is the primary tool for agents that need to move funds.

| Parameter           | Type   | Required | Description                                                              |
| ------------------- | ------ | -------- | ------------------------------------------------------------------------ |
| `account_id`        | string | Yes      | Account ID                                                               |
| `action`            | string | Yes      | `"earn"`, `"swap"`, `"withdraw"`, `"transfer"`, `"borrow"`, or `"repay"` |
| `amount`            | string | Varies   | Amount in smallest unit                                                  |
| `asset`             | string | Varies   | Asset symbol                                                             |
| `network`           | string | Yes      | Target network                                                           |
| `protocol`          | string | Varies   | Protocol (for earn/withdraw)                                             |
| `sell_asset`        | string | Varies   | Asset to sell (for swap)                                                 |
| `buy_asset`         | string | Varies   | Asset to buy (for swap)                                                  |
| `sell_amount`       | string | Varies   | Amount to sell (for swap)                                                |
| `buy_amount`        | string | Varies   | Amount to buy (for swap)                                                 |
| `recipient`         | string | Varies   | Recipient address (for transfer)                                         |
| `collateral_amount` | string | Varies   | Collateral amount (for borrow/repay)                                     |
| `collateral_asset`  | string | Varies   | Collateral asset (for borrow/repay)                                      |

**Returns:** `{plan_id, activity_id, status, action}` — the execution result. Use `get_activities` with the `activity_id` to poll execution status.

**Example — earn yield:**

```json theme={null}
{
  "account_id": "acc_xxx",
  "action": "earn",
  "amount": "1000000",
  "asset": "USDC",
  "network": "base",
  "protocol": "compound"
}
```

**Example — swap:**

```json theme={null}
{
  "account_id": "acc_xxx",
  "action": "swap",
  "sell_asset": "USDC",
  "buy_asset": "WETH",
  "sell_amount": "1000000",
  "network": "base"
}
```

<Tip>
  `plan_and_execute` eliminates the three-step flow (create plan → sign digest → execute). The agent makes one tool call and gets back the execution result. This only works on the local MCP server because it needs access to the P256 key.
</Tip>

### `create_plan` (local only)

Create a plan for any action type. Similar to the remote server's `create_earn_plan` / `create_swap_plan` but unified into one tool.

| Parameter    | Type   | Required | Description                                                              |
| ------------ | ------ | -------- | ------------------------------------------------------------------------ |
| `account_id` | string | Yes      | Account ID                                                               |
| `action`     | string | Yes      | `"earn"`, `"swap"`, `"withdraw"`, `"transfer"`, `"borrow"`, or `"repay"` |

Plus the same action-specific parameters as `plan_and_execute`.

**Returns:** Full plan details including `plan_id`, `digest`, `expires_at`.