MCP Guide
Definitive has an MCP server (@definitive-fi/mcp) that lets AI assistants — Claude, Cursor, and others — interact with your portfolio. Check positions, review transfers, look up orders, trade, bridge assets cross-chain, and more through natural language.
Prerequisites
You'll need a Definitive API key and secret. See the Overview page for instructions on generating credentials.
Installation
Add the following to your MCP client configuration (e.g., Claude Desktop, Claude Code, Cursor):
{
"mcpServers": {
"definitive": {
"command": "npx",
"args": ["-y", "@definitive-fi/mcp@latest"],
"env": {
"DEFINITIVE_API_KEY": "dpka_...",
"DEFINITIVE_API_SECRET": "dpks_...",
"DEFINITIVE_API_KEY_TYPE": "portfolio"
}
}
}
}Set DEFINITIVE_API_KEY_TYPE to organization if you are using an organization API key.
Environment Variables
| Variable | Description |
|---|---|
DEFINITIVE_API_KEY | Your Definitive API key |
DEFINITIVE_API_SECRET | Your Definitive API secret |
DEFINITIVE_API_KEY_TYPE | portfolio or organization — determines which tools are available |
Available Tools
Portfolio / Order Information Tools
These tools are available with both portfolio and organization API keys.
| Tool | Description |
|---|---|
list_positions | List current token holdings with balances, USD values, and P&L |
get_portfolio | Get portfolio details including vaults, addresses, chains, and signers |
list_transfers | List historical transfers (deposits, withdrawals, swaps, bridges) |
get_deposit_address | Get a deposit address for a specific blockchain |
list_orders | List trade orders with optional status filtering |
get_order_details | Get detailed information about a specific order |
Trading Tools
These tools are available with both portfolio and organization API keys.
| Tool | Description |
|---|---|
get_trade_quote | Get a price quote for a trade order (market, limit, TWAP, stop, stop-loss, take-profit) |
submit_trade | Submit a trade order using a quote from get_trade_quote |
cancel_trade | Cancel a pending trade order |
get_quicktrade_quote | Get a price quote for a QuickTrade market swap |
quicktrade | Execute a QuickTrade market swap immediately |
cancel_quicktrade | Cancel a pending QuickTrade order |
Bridging Tools
These tools are available with both portfolio and organization API keys.
| Tool | Description |
|---|---|
bridge_quote | Get quotes for a cross-chain bridge transfer |
bridge_submit | Execute a cross-chain bridge transfer |
Perps Tools
Perpetual futures market data, account reads, order previews, and transfers. Symbols follow the subvenue:SYMBOL convention (e.g. native:BTC for the core exchange); a bare symbol works only while exactly one market uses it.
| Tool | Description |
|---|---|
perps_list_markets | List all perps markets with live prices, funding, and open interest |
perps_get_orderbook | L2 orderbook snapshot for a market |
perps_get_candles | OHLCV candles (defaults to the last 24h) |
perps_get_quote | Size-aware execution estimate against the live book |
perps_get_funding | Historical + predicted funding for a market |
perps_get_account | Account equity, margin usage, and open positions |
perps_get_account_status | Perps onboarding state (NO_ACCOUNT → READY) |
perps_list_open_orders | Orders resting on the venue |
perps_get_order_history | Historical orders with final status |
perps_list_fills | Trade fills with fees and closed PnL |
perps_list_funding_payments | Funding paid/received on positions |
perps_get_fees | Current perps taker/maker fee rates |
perps_preview_order | Validate a proposed order and preview its cost and margin (nothing is placed) |
perps_get_deposit_quote | Quote a deposit from a trading vault into the perps account |
perps_deposit | Execute a deposit quote (moves funds) |
perps_get_withdraw_payload | Get the EIP-712 payload for a withdrawal to the Arbitrum trading vault |
perps_submit_withdraw | Submit the account owner's signature to execute the withdrawal |
Order previews, deposits, and withdrawals require a WRITE-scoped key. Withdrawals must be signed by the perps account owner wallet (accountOwnerAddress from perps_get_account_status); the MCP server cannot sign, so the agent needs a wallet signature from you. See Deposit to Perps and Withdraw from Perps.
Organization-Level Tools
These tools are only available with organization API keys.
| Tool | Description |
|---|---|
list_portfolios | List all portfolios in the organization |
get_fees | Get fee summary for a portfolio over a time period |
create_portfolio | Create a new portfolio in the organization |