Content
# Definitive Flash MCP
An [MCP](https://modelcontextprotocol.io) server that lets traders quote, execute, and manage
trades on the [Definitive Flash API](https://flash.definitive.fi/docs) 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`](https://www.npmjs.com/package/@definitive-fi/flash-mcp) — no clone
or build needed. Pick your client:
### Claude Code
```bash
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
[](https://cursor.com/en/install-mcp?name=definitive-flash&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBkZWZpbml0aXZlLWZpL2ZsYXNoLW1jcCJdfQ%3D%3D)
Or add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project):
```json
{
"mcpServers": {
"definitive-flash": {
"command": "npx",
"args": ["-y", "@definitive-fi/flash-mcp"]
}
}
}
```
### Codex
```bash
codex mcp add definitive-flash -- npx -y @definitive-fi/flash-mcp
```
Or add to `~/.codex/config.toml`:
```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:
```json
{
"mcpServers": {
"definitive-flash": {
"command": "npx",
"args": ["-y", "@definitive-fi/flash-mcp"]
}
}
}
```
### From source (development)
```bash
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:
```bash
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:
```bash
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.
- **Native gas assets are handled for you.** Flash prices token contracts, not the raw gas asset,
so referencing native ETH/BNB/POL/AVAX/HYPE/XPL/SOL (a bare symbol, `native`, the zero address,
or the `0xEeee…` sentinel) is automatically routed through the chain's wrapped-native token —
wrapping the spent amount first when needed. Every substitution is noted in the quote/order
output. You end up holding the wrapped token (e.g. WETH); unwrap separately if you need native.
- `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.
