> ## 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 Setup
> Connect any AI agent to Legend via MCP — Claude Code, Cursor, and more
# 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
```bash theme={null}
# 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
```bash theme={null}
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:
```json theme={null}
{
"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:
```json theme={null}
{
"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.
No API key needed — authenticate with your Google account.
```bash theme={null}
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](https://dashboard.legend.xyz) under **Settings > API Keys**.
```bash theme={null}
claude mcp add --transport http legend-remote https://prime-api.legend.xyz/mcp \
--header "Authorization: Bearer qk_YOUR_KEY_HERE"
```
```json theme={null}
{
"mcpServers": {
"legend-remote": {
"url": "https://prime-api.legend.xyz/mcp",
"headers": {
"Authorization": "Bearer qk_YOUR_KEY_HERE"
}
}
}
}
```
```json theme={null}
{
"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
```bash theme={null}
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:
```bash theme={null}
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:
```markdown theme={null}
## 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 |