MCP Setup

Legend’s MCP server works with any MCP-compatible agent host: Claude Code, Cursor, OpenAI Responses API, and others. Legend offers two servers: a local server (recommended) that runs on your machine with full signing capabilities, and a remote server for read-only or shared access.

Local MCP Server (recommended)

The local server runs via legend-cli mcp serve and includes all tools plus plan_and_execute — create, sign, and execute in one tool call. No separate signing step.

Install and authenticate

# Install the CLI
brew install legend-hq/tap/legend-cli   # macOS
# or: cargo install legend-cli          # any platform

# Log in with Google
legend-cli login

Connect to your agent host

Claude Code
Cursor
Any MCP host

claude mcp add legend -- legend-cli mcp serve

Verify with /mcp — you should see “legend” with a green status and tools like list_accounts, get_portfolio, plan_and_execute.

Add to .cursor/mcp.json or Settings > MCP:

{
  "mcpServers": {
    "legend": {
      "command": "legend-cli",
      "args": ["mcp", "serve"]
    }
  }
}

Any host that supports stdio MCP servers works. The server command is:

legend-cli mcp serve

Refer to your agent host’s documentation for how to register a stdio MCP server.

Team Projects (`.mcp.json`)

Share the local MCP config with your team by committing a .mcp.json at the project root:

{
  "mcpServers": {
    "legend": {
      "command": "legend-cli",
      "args": ["mcp", "serve"]
    }
  }
}

Each team member runs legend-cli login once to authenticate with their own account.

Remote MCP Server

The remote server at https://prime-api.legend.xyz/mcp is best for read-only operations or when you don’t need local signing.

Claude Code (OAuth)
Claude Code (Query Key)
Cursor
OpenAI Responses API

No API key needed — authenticate with your Google account.

claude mcp add --transport http legend-remote https://prime-api.legend.xyz/mcp

Then in Claude Code:

/mcp

Select “legend-remote” > “Authenticate” > sign in with Google. A Prime Account is created automatically if you don’t have one.

Get a query key from dashboard.legend.xyz under Settings > API Keys.

claude mcp add --transport http legend-remote https://prime-api.legend.xyz/mcp \
  --header "Authorization: Bearer qk_YOUR_KEY_HERE"

{
  "mcpServers": {
    "legend-remote": {
      "url": "https://prime-api.legend.xyz/mcp",
      "headers": {
        "Authorization": "Bearer qk_YOUR_KEY_HERE"
      }
    }
  }
}

{
  "model": "gpt-4o",
  "input": "Check my Legend portfolio",
  "tools": [
    {
      "type": "mcp",
      "server_label": "legend-remote",
      "server_url": "https://prime-api.legend.xyz/mcp",
      "authorization": "Bearer qk_YOUR_KEY_HERE",
      "require_approval": "never"
    }
  ]
}

Local vs Remote: When to Use Which

	Local MCP	Remote MCP
Signing	Built-in — `plan_and_execute` does everything	Requires separate CLI call for signing
Auth	`legend-cli login` (Google SSO, 30-day JWT)	OAuth or query key
Setup	Install CLI + register server	Just register server URL
Team sharing	Each person runs their own	Shared via query key
Best for	Agents that execute transactions	Read-only dashboards, shared team access

Setting Up Signing

To execute plans (move funds), you need a P256 signing key. Read-only operations work without it.

With Local MCP (easiest)

Ask your agent:

“Create a new Legend account with keygen”

The create_account tool generates a P256 key in macOS Keychain and creates the account in one step. Then plan_and_execute handles signing automatically on every subsequent call.

With CLI

legend-cli accounts create --keygen

This generates a P256 key in macOS Keychain, creates a Turnkey-backed sub-account, and saves the key reference to your profile.

Sign Plan Digests (remote MCP only)

When using the remote MCP server, the agent creates a plan via MCP and gets back a digest. To execute:

legend-cli sign 0xabc123...
# Output: 0xdef456... (the EIP-712 signature)

Agent System Prompt Snippet

Add this context to your agent’s system prompt or project instructions file (CLAUDE.md, AGENTS.md, etc.) so it uses Legend tools correctly:

## Legend

This project uses Legend for DeFi operations via MCP tools.

- **Amounts** are in smallest units: 1 USDC = 1000000 (6 decimals), 1 ETH = 1e18
- **Plans** expire after 2 minutes — execute promptly after creation
- **yield_markets** keys: comet -> "compound", aave -> "aave", morpho_vault -> "morpho_vault"
- Use `plan_and_execute` for one-shot plan creation + signing + execution
- Call `list_accounts` first if you don't know the account ID
- Call `get_portfolio` to see balances and yield markets before creating plans

Troubleshooting

Issue	Fix
”401 Unauthorized”	Run `legend-cli login` or check your query key
Tools not appearing	Check your agent host’s MCP status panel
”Account not found” on tool call	Use `list_accounts` to get valid account IDs
Plan expired	Plans last 2 minutes — create a new one and execute promptly
”No profile found” on sign	Run `legend-cli login` then `legend-cli accounts create --keygen`
Local MCP not connecting	Verify `legend-cli mcp serve` runs without errors in your terminal

Getting Started

Guides

Concepts

Accounts

Portfolio

Plans

Activities & Events

Reference Data

SDKs

Agent Integration

MCP Server

Agent Guides

MCP Setup

MCP Setup

Local MCP Server (recommended)

Install and authenticate

Connect to your agent host

Team Projects (`.mcp.json`)

Remote MCP Server

Local vs Remote: When to Use Which

Setting Up Signing

With Local MCP (easiest)

With CLI

Sign Plan Digests (remote MCP only)

Agent System Prompt Snippet

Troubleshooting

​MCP Setup

​Local MCP Server (recommended)

​Install and authenticate

​Connect to your agent host

​Team Projects (.mcp.json)

​Remote MCP Server

​Local vs Remote: When to Use Which

​Setting Up Signing

​With Local MCP (easiest)

​With CLI

​Sign Plan Digests (remote MCP only)

​Agent System Prompt Snippet

​Troubleshooting

MCP Setup

Local MCP Server (recommended)

Install and authenticate

Connect to your agent host

Team Projects (`.mcp.json`)

Remote MCP Server

Local vs Remote: When to Use Which

Setting Up Signing

With Local MCP (easiest)

With CLI

Sign Plan Digests (remote MCP only)

Agent System Prompt Snippet

Troubleshooting