Definitive Flash MCP

An MCP server that lets traders quote, execute, and manage trades on the Definitive Flash API directly from any MCP client (Claude Code, Claude Desktop, Cursor, etc.).

Flash routes across 200+ liquidity sources on 12 chains and returns a signable payload. This server handles the full flow for you: quote → wrap/approve → sign → submit → poll for fill, for both EVM wallets and Solana.

What it does

| Tool | Purpose | |------|---------| | flash_setup | Connect your account: get a link to generate a Flash API key, then store the key and your funder wallet(s). | | flash_status | Show what's configured (API key, wallets) and the supported chains. | | flash_quote | Price a trade without executing. No wallet required. | | flash_balances | Native + token balances for any wallet, via the built-in per-chain RPCs. Read-only. | | flash_submit_order | Execute a trade end to end (market, limit, twap, stop, take-profit, bracket). Spends real funds. | | flash_get_order | Status, fills, and detail for one order. | | flash_list_orders | Recent orders for a funder wallet. | | flash_cancel_order | Cancel a resting order. |

Install

The server is published to npm as @definitive-fi/flash-mcp — no clone or build needed. Pick your client:

Claude Code

claude mcp add definitive-flash -- npx -y @definitive-fi/flash-mcp

Or install the plugin, which bundles the server plus a trading-workflow skill:

/plugin marketplace add DefinitiveCo/flash-mcp
/plugin install definitive-flash@flash-mcp

Cursor

Or add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "definitive-flash": {
      "command": "npx",
      "args": ["-y", "@definitive-fi/flash-mcp"]
    }
  }
}

Codex

codex mcp add definitive-flash -- npx -y @definitive-fi/flash-mcp

Or add to ~/.codex/config.toml:

[mcp_servers.definitive-flash]
command = "npx"
args = ["-y", "@definitive-fi/flash-mcp"]

Claude Desktop / other clients

Add the same stdio server to the client's config JSON:

{
  "mcpServers": {
    "definitive-flash": {
      "command": "npx",
      "args": ["-y", "@definitive-fi/flash-mcp"]
    }
  }
}

From source (development)

cd flash-mcp
bun install      # or: npm install
bun run build    # compiles to dist/
claude mcp add definitive-flash -- node "$PWD/dist/index.js"

First-run setup

Run the interactive wizard in your own terminal:

npx -y @definitive-fi/flash-mcp setup

It walks through everything in one pass:

1. Opens the Definitive MCP setup page (app.definitive.fi/account/organization/mcp-setup) — log in, click Generate API Key, Copy & Close — and prompts you to paste the key.
2. Prompts for your EVM funder wallet private key (press Enter to skip).
3. Prompts for your Solana funder wallet secret (press Enter to skip — you can add either later).
4. Prompts for custom RPC endpoints per chain, pre-filled with the public defaults (which are rate-limited — a personal endpoint is recommended if you trade often).

Secrets are typed into hidden prompts and written straight to the macOS Keychain — they never appear on screen, in shell history, or in any chat transcript. Every step can be skipped and the wizard re-run at any time.

That's it — in your MCP client, flash_status to confirm, flash_quote to price, flash_submit_order to trade.

Never paste a wallet private key into the chat — it would pass through the model and the conversation transcript. The flash_setup tool does not accept private keys; wallets are added only via the wizard or CLI below. (The API key alone is safe to paste in chat if you prefer — it can't move funds — via flash_setup { "apiKey": "dpka_…" }; it enables quoting.)

Individual CLI commands

Each wizard step is also available as a one-shot command:

flash-mcp set-key evm     # or: svm, api   (prompts hidden, stores in Keychain)
flash-mcp set-key api
flash-mcp set-rpc base https://your-rpc
flash-mcp set-org 5VYFCW7M
flash-mcp status          # show what's configured
flash-mcp remove-key evm

If it isn't on your PATH, run it via npx: npx -y @definitive-fi/flash-mcp set-key evm.

Credential storage

Secrets are stored in the macOS Keychain (service definitive-flash-mcp), encrypted at rest by the OS — never written to a dotfile in plaintext. On non-macOS hosts, or to inject credentials without calling flash_setup, set environment variables (these take precedence over the Keychain):

DEFINITIVE_API_KEY            your Flash API key
DEFINITIVE_PRIVATE_KEY        EVM funder wallet private key (0x hex)
DEFINITIVE_SVM_PRIVATE_KEY    Solana funder wallet secret (base58 or JSON byte array)

RPC endpoints default to public nodes per chain (rate-limited). Set your own the easy way via flash_setup with { "rpc": { "base": "https://…" } } — persisted to ~/.config/definitive-flash-mcp/config.json (non-secret, hand-editable). Precedence, highest first: per-call rpcUrl argument → DEFINITIVE_RPC_<CHAIN> env var → flash_setup config → public default.

Notes

• flash_submit_order spends real funds. It quotes fresh, signs with your stored key, and submits. For market orders it polls until the order reaches a terminal status.
• EVM trades may send a one-time ERC-20 approve (and a wrap tx for native-asset trades) before signing — your wallet needs a little gas for those.
• qty is the amount being spent: in contraAsset units for buys, targetAsset units for sells.
• Supported chains: ethereum, optimism, bsc, polygon, base, arbitrum, avalanche, hyperevm, robinhood, plasma, monad, solana.