MCP

Model Context Protocol (MCP)

The Lavarage API documentation supports Model Context Protocol (MCP), allowing AI assistants like Claude, Cursor, and other MCP-compatible tools to read and interact with our API docs directly.

You can also connect AI assistants to the Lavarage Trader MCP server, which exposes a comprehensive set of trading tools (24 trading tools at last count — see the trader-mcp tool reference allTools for the live list) for placing trades, querying positions, managing TP/SL orders, and more.

Choosing How to Connect

There are two ways to run the Trader MCP server:

Local Mode (Recommended)

Run the trader-mcp server on your own machine and point your MCP-compatible client at it. You hold your own API key and full control over the integration.

Setup:

1. Clone the trader-mcp repo and install:

```
git clone https://github.com/pinedefi/trader-mcp.git
cd trader-mcp
npm install && npm run build
```

2. Set your Lavarage API key as an env var:

```
export LAVARAGE_API_KEY=your_key_here
```

3. Add to your MCP client config (Claude Desktop / Cursor / etc.). Example for Claude Desktop claude_desktop_config.json:

```json
{
"mcpServers": {
"lavarage": {
"command": "node",
"args": ["/absolute/path/to/trader-mcp/dist/index.js"],
"env": {
"LAVARAGE_API_KEY": "your_key_here"
}
}
}
}
```

4. Restart your MCP client. The Lavarage trading tools will appear in the tool list.

Hosted Mode (Beta)

Warning — Hosted Mode is currently in beta. Auth delegation has a known issue (LAV-917 — invalid Privy key quorum ID in production). Use Local Mode for production integrations until further notice. Track LAV-917 for status updates.

When the OAuth/Privy delegation flow is stable, you'll be able to point any MCP-compatible client at our hosted endpoint and authenticate via your Lavarage wallet — no local install or API key management required:

```
https://mcp.lavarage.xyz/mcp
```

This endpoint accepts OAuth/Privy delegated credentials so the AI assistant trades on behalf of your wallet without you exporting a long-lived API key. Once LAV-917 ships, this guide will be updated with the connection steps and the "Recommended" label will move here.

What MCP Documentation Mode Does

In addition to the trading tools above, this site itself can be browsed by an MCP-compatible AI as a documentation source. When you connect, the assistant can:

• Browse all API endpoints — understand available operations, parameters, and response formats
• Read guides — access trading concepts, authentication details, and code examples
• Help you integrate — generate working code against the Lavarage API with accurate, up-to-date information

If your AI tool supports MCP documentation sources, point it at:

```
https://lavarage-api.readme.io
```

The assistant will automatically discover the API reference and guide pages.

Supported Clients

Any MCP-compatible client can connect, including:

• Claude (via MCP server configuration)
• Cursor (via MCP settings)
• Other MCP clients — see modelcontextprotocol.io for the full ecosystem

Server-Sent Events (Live Position Updates)

Trader-MCP tools (and any custom integration) can subscribe to live position events over SSE:

```
GET https://api.lavarage.xyz/api/v1/sse?owner=YOUR_WALLET&apiKey=YOUR_KEY
```

The endpoint is /api/v1/sse — not /sse. The connection emits position.open, position.close, position.liquidated, and order.triggered events keyed off the supplied wallet.

Required Parameters for *-by-token Tools

The quote-by-token and open-by-token MCP tools wrap the corresponding HTTP endpoints. Both require:

side on *-by-token endpoints only accepts LONG or SHORT. Borrow flow uses different endpoints (POST /api/v1/positions/borrow family) — passing side: "BORROW" here returns a 400.

For SOL LONG via MCP, pass quoteTokenMint set to the USDC mint (EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v) — defaulting both base and quote to WSOL returns 404 NO_OFFER_FOR_TOKEN (there's no SOL/SOL offer).