Skip to main content

​
Using with OpenAI Agents

Legend Prime’s MCP server works natively with the OpenAI Responses API. Pass the server URL and the model discovers tools automatically.

​
Setup

Add Legend as an MCP tool source in your Responses API call: 
import openai

client = openai.OpenAI()

response = client.responses.create(
    model="gpt-4o",
    input="Check my Legend portfolio and find the best yield for USDC",
    tools=[
        {
            "type": "mcp",
            "server_label": "legend-remote",
            "server_url": "https://prime-api.legend.xyz/mcp",
            "authorization": f"Bearer {LEGEND_QUERY_KEY}",
            "require_approval": "never",
        }
    ],
)
The first response includes an mcp_list_tools output with all available tools. The model then decides which to call.

​
Tool Discovery

On the first request, the API fetches tools: 
{
  "type": "mcp_list_tools",
  "server_label": "legend-remote",
  "tools": [
    {"name": "list_accounts", "description": "...", "input_schema": {...}},
    {"name": "get_portfolio", "description": "...", "input_schema": {...}},
    {"name": "create_earn_plan", "description": "...", "input_schema": {...}}
  ]
}
As long as mcp_list_tools is in the conversation context, the API won’t re-fetch on subsequent turns.

​
Tool Calls

When the model calls a tool, you see mcp_call items: 
{
  "type": "mcp_call",
  "name": "get_portfolio",
  "arguments": "{\"account_id\": \"acc_xxx\"}",
  "output": "{\"balances\": {...}, \"yield_markets\": {...}}"
}

​
Handling Plan Execution

Read-only operations (list_accounts, get_portfolio, list_assets) work seamlessly. For plan execution, your orchestrator needs to handle signing: 
# 1. Agent creates a plan (via MCP tool call)
# Response includes mcp_call with create_earn_plan → {plan_id, digest}

# 2. Your orchestrator signs the digest
import subprocess

plan_id = extract_plan_id(response)
digest = extract_digest(response)

# Sign using the legend-cli CLI
result = subprocess.run(
    ["legend-cli", "sign", digest],
    capture_output=True, text=True
)
signature = result.stdout.strip()

# 3. Feed the signature back to the agent
response = client.responses.create(
    model="gpt-4o",
    input=f"Execute the plan with signature: {signature}",
    previous_response_id=response.id,
    tools=[...],  # same MCP config
)
Alternatively, use --auto-sign on the CLI for a simpler flow: 
result = subprocess.run(
    ["legend-cli", "plan", "execute", account_id,
     "--plan-id", plan_id, "--auto-sign", "--json"],
    capture_output=True, text=True
)

​
Filtering Tools

If you only need a subset of tools, use allowed_tools: 
{
    "type": "mcp",
    "server_label": "legend-remote",
    "server_url": "https://prime-api.legend.xyz/mcp",
    "authorization": f"Bearer {LEGEND_QUERY_KEY}",
    "allowed_tools": ["list_accounts", "get_portfolio", "list_assets"],
}
This is useful for read-only agents that shouldn’t create plans.

​
System Prompt

Add domain context for better tool usage: 
You have access to Legend Prime tools for DeFi portfolio management.

Key facts:
- Amounts are in smallest units: 1 USDC = 1000000 (6 decimals)
- Plans are free previews that expire after 2 minutes
- yield_market keys: comet → "compound", aave → "aave", morpho_vault → "morpho_vault"
- Call list_accounts first to discover account IDs
- Call get_portfolio to see balances and yield rates before creating plans