Provides pre-trade risk checks for Binance spot trading, using live market data and order book depth to return CLEARED, REFUSED, or UNREADABLE verdicts before an order is placed.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@preflight-mcp Preflight this order: buy 0.5 BTC at market"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A pre-trade guard for AI agents that have been given trading authority.
An MCP server that answers one question before an order is placed: should this
order be placed at all? It returns CLEARED, REFUSED, or UNREADABLE, with
the numbers that produced the answer.
Built for the Binance Agent OS Mini Hackathon — Track A, Trading Workflows.
CLEARED An ordinary trade
"Buy a small amount of BTC."
✓ 0 bps slippage, 0 bps spread, quote 1263ms old
REFUSED Size the book cannot carry
"Go long BTC with everything."
✗ the visible book holds 5.31328 of the 500 this order wants — the rest
has no price at all, and a market order would find whatever is behind it.
REFUSED A misplaced decimal
"Set a limit buy at 900000." (the model meant 90000)
✗ the limit price 900000 sits 1032.3% outside the 24h range of
77620.01–79485 — far enough out that a misplaced decimal is the
likeliest explanation.
REFUSED A trade that is really a position
"Buy BTC." — with 500 USDT free, and no instruction about size.
✗ this order is 39.4% of the 500 free balance, over the 25% ceiling —
a position decision rather than a trade, and not one to take unattended.
UNREADABLE The data never arrived
"Buy BTC." — with the market endpoint down.
✗ could not establish bid, ask, order book for BTCUSDT — this is not a
judgement about the order, it is the absence of one. A failed read is
not permission.
1 of 7 orders cleared. The other 6 would all have been accepted by the venue.That last line is the whole argument. None of those six orders would have been rejected. They are well-formed, affordable, and the exchange takes them.
Agent OS gives an agent spot, margin, convert and futures authority through one MCP connection. That is the right thing to build, and it moves the dangerous part somewhere new: the model now decides when and how much, and models are bad at exactly the parts of that which are arithmetic rather than judgement.
An LLM does not know that the quote it is reasoning from is forty seconds old.
It does not walk an order book to find out what its own order does to the price
it gets. It cannot tell a null from a 0, so a market-data request that
quietly failed reads as a market that is quietly fine.
The venue will not save you here. A venue rejects malformed orders — wrong lot size, insufficient balance. It accepts, without comment, an order that walks the book 300 bps, an order priced off stale data, and an order that puts 40% of an account into one position. Those are the expensive ones, and nothing was checking them.
So: a guard that runs before execution, holds no credentials, and cannot move funds even if it is wrong.
A failed read is not permission.
UNREADABLE is a distinct outcome from REFUSED because they call for
different responses. REFUSED means the order is wrong — reprice it, resize it,
pick another moment. UNREADABLE means we never established anything: the order
may be perfect, and we cannot say. An agent told "refused" goes looking for a
better price. An agent told "unreadable" should stop and retry the read.
Most guards collapse the two, or worse, treat a failed fetch as an empty result
and pass it through as though the market were fine. This one is built around not
doing that. Anything it could not read comes back null and is named.
Related MCP server: Aegis
git clone https://github.com/tinoxbt/preflight-mcp.git
cd preflight-mcp
npm install
npm run buildAdd it to Claude Code:
claude mcp add preflight -- node /absolute/path/to/preflight-mcp/dist/server.jsOr in claude_desktop_config.json / any MCP client:
{
"mcpServers": {
"preflight": {
"command": "node",
"args": ["/absolute/path/to/preflight-mcp/dist/server.js"]
}
}
}No API key, no account, no OAuth. It reads public market data only.
The point is to pair it with the server that actually executes:
claude mcp add binance-mcp-server --transport http https://agent.binance.com/mcp/agentic
claude mcp add preflight -- node /absolute/path/to/preflight-mcp/dist/server.jsThen give the agent one instruction:
Before placing any order through the Binance MCP server, call
preflight_tradewith the same symbol, side and quantity. If the verdict is notCLEARED, do not place the order — report the finding instead.
The division of labour is deliberate. Binance MCP holds the OAuth session and places orders. preflight-mcp holds nothing and places nothing. A bug in the guard cannot cost you money; it can only cost you a trade.
Tool | What it does |
| The gate. Symbol, side, quantity, optional limit price and balance → |
| The facts a decision rests on, with their age stated. Unread fields are |
| Every active threshold and the environment variable that changes it. A guard nobody can inspect is a guard nobody can argue with. |
Rule | Default | Env | Why |
| 5 s |
| A quote older than this is history, not a price. |
| 50 bps |
| Crossing it costs more than the trade is likely to make. |
| 100 bps |
| What the order does to its own price, walked across the live book. |
| — | — | The order is larger than the visible book. Absence, not expense — reported separately. |
| 25% of free balance |
| Past this it is a position decision. Skipped entirely unless a balance is supplied. |
| 20% outside 24h range |
| A fat-finger catch for limit orders, judged against the pair's own day. |
| from the venue | — | The venue's own filters, checked before it has to reject the order. |
Defaults lean towards refusing, because the two errors do not cost the same. A refusal costs a round trip and a message. A bad fill costs money and does not come back.
UNREADABLE is not in the table because it is not a rule. It is what happens
when the facts cannot be established, and it always refuses.
Slippage is measured, not assumed. walkBook consumes real levels and
returns the average fill price across all of them. The top of book is not the
price a 500 BTC order gets.
Both sides of the book. A buy walks the asks, a sell walks the bids. A guard that checked one side would clear a sell into a hollow bid stack.
Position size is skipped, not guessed. Omit quoteBalance and that rule
does not run. Inventing a balance would be the exact failure this project is
about.
Every refusal cites its number. There is a test asserting it. A refusal an operator cannot check is an obstacle rather than a safeguard.
Symbol filters are cached for an hour — successes only. A failed lookup is never cached as "no filters", which would turn one bad minute into an hour of orders checked against nothing.
npm testTwelve tests over the pure rules, each one a thing that actually goes wrong when an agent trades unattended: stale quotes, hollow books, wrong side, fat fingers, dust, absent data. They run against fixtures rather than a venue, so they are deterministic and need no network.
npm run demo # the scenarios above, against the live venueSpot only. Futures and margin have their own failure modes — leverage, liquidation distance, funding — and this build does not model them. It should.
The visible book is not the whole book. Iceberg and hidden liquidity mean
book_too_thin can be pessimistic. That is the safe direction, but it is a
real limitation, not a feature.
It cannot enforce anything. It is advice an agent must be instructed to ask for. A guard that could enforce would need to sit in the execution path and hold credentials, which is the trade-off this deliberately does not make.
Public data host by default. api.binance.com returns HTTP 451 from many
hosts; the default is Binance's public market-data mirror
(data-api.binance.vision), same endpoints and numbers. Override with
BINANCE_API_BASE.
The rules are not invented for a hackathon. They are ported from a Rust mint sniper the author has been running against live money, where the same principle was learned the expensive way — an unreadable value read as zero cost 229,074 gas across six wallets in a single run. That codebase's preflight module refuses to arm on a value it could not establish, for the same reason this one refuses to clear a trade.
MIT.
The market facts a trading decision rests on, with their age stated: top of book, spread, 24h range, book depth, and the venue's own lot and notional filters. Fields that could not be read come back null and are listed in missing — they are never filled in with zero.
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | Venue symbol, e.g. ETHUSDT | |
| depthLimit | No | Book levels per side (default 100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does well: it discloses that field ages are stated, unreadable fields return null and are listed in 'missing', and nulls are never replaced with zeros. It does not explicitly say the operation is read-only or mention authentication or rate limits, but 'snapshot' and the absence of mutation signals make the safety profile reasonably clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The first sentence front-loads the purpose and scope, the second adds a crucial data-quality caveat about null handling. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter snapshot tool with no output schema, the description covers the important output behaviors: what market facts are included, that ages are stated, and how missing fields are represented. It does not describe exact response formatting, but the core information an agent needs to select and interpret the call is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level meaning beyond the schema, but the schema already fully documents symbol and depthLimit with constraints and examples, so the agent is not left guessing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a market snapshot and enumerates specific contents: top of book, spread, 24h range, book depth, and lot/notional filters. It lacks a single strong verb like 'retrieves' or 'gets', but 'The market facts a trading decision rests on' combined with the tool name makes the purpose clear and implicitly distinguishes it from the preflight siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrasing 'a trading decision rests on' implies this is the tool to consult for current market conditions before trading, but it does not explicitly state when to prefer it over preflight_trade or preflight_rules, nor does it mention any exclusions. Usage context is present but not directly actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The thresholds every decision is measured against, and the environment variable that changes each one. A guard whose rules cannot be read is a guard nobody can argue with, and an operator who cannot see the ceiling cannot tell a refusal from a bug.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It reveals that an environment variable can change each threshold and that this tool exposes those thresholds, which is useful. However, it does not explicitly state whether the operation is read-only, what the output contains, or how the environment variable affects the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The first sentence is informative and front-loaded. The second sentence is rhetorical and metaphorical, adding emphasis but no concrete operational detail; it does not fully 'earn its place' in an AI-facing description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with no parameters, but there is no output schema and no annotations. The description states that thresholds and their environment-variable dependencies are shown, yet it omits the actual environment variable name and the return shape, leaving minor but real gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no schema burden to compensate for. The mention of an environment variable that changes thresholds is the only semantic detail relevant to invocation, and it is adequate for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The title 'Show the active rules' provides a clear verb and resource, and the description adds that these are the 'thresholds every decision is measured against.' It is distinguishable from siblings like preflight_trade by focusing on rules/thresholds rather than execution, though it does not explicitly name an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the rules matter for decisions ('every decision is measured against'), but it gives no explicit guidance on when to call this tool versus preflight_trade or market_snapshot. There are no stated exclusions, prerequisites, or recommended call contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Decide whether an order should be placed, BEFORE placing it. Returns CLEARED, REFUSED or UNREADABLE with the numbers behind the answer: spread, expected slippage against the live book, quote age, position size, and venue filters. UNREADABLE means the market data could not be established — treat it as a refusal, not as permission. Call this before every order placed by an execution tool.
| Name | Required | Description | Default |
|---|---|---|---|
| side | Yes | ||
| symbol | Yes | Venue symbol, e.g. BTCUSDT | |
| quantity | Yes | Size in the base asset, e.g. 0.01 for BTC | |
| limitPrice | No | Limit price. Omit for a market order. | |
| quoteBalance | No | Free balance in the quote asset. Supply it and the position-size rule applies; omit it and that one rule is skipped rather than guessed at. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the outcome values, lists the supporting data returned, and explicitly defines the meaning of UNREADABLE to prevent dangerous misinterpretation. It does not detail side effects or rate limits, but this is a preflight check and the description's framing makes non-execution clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler: the core purpose is front-loaded, the return semantics are listed compactly, and the critical UNREADABLE warning and invocation rule each earn their place. Nothing extraneous remains.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description supplies the essential return values, their meaning, and the required call context. It could name the sibling tools to help distinguish from market_snapshot and preflight_rules, but the description is otherwise sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, so the schema already documents most parameters. The description adds value by indicating which data feeds the decision (spread, slippage, quote age, position size, venue filters) but does not meaningfully elaborate on individual parameter semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Decide whether an order should be placed') and a specific resource (a trade before execution), and clearly differentiates from siblings by focusing on pre-execution decision rather than snapshotting or rules. The three return statuses make the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs 'Call this before every order placed by an execution tool', giving clear when-to-use guidance. It also explains how to interpret UNREADABLE as refusal. It does not explicitly name the sibling tools as alternatives, so it misses a small opportunity to state when NOT to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0market_snapshotpreflight_rulespreflight_tradeScored across 3 tools
Each tool has a clearly distinct role: preflight_trade returns a decision, market_snapshot provides raw market data, and preflight_rules exposes configurable thresholds. There is no overlap or ambiguity about which tool to call.
Two tools share the preflight_ prefix and all names use clear, lowercase snake_case. market_snapshot breaks the prefix pattern but is still intuitively named and consistent in style.
Three tools is a well-scoped set for the server's purpose: one decision tool, one data source, and one rules reference. Each tool earns its place with no unnecessary clutter.
The tool surface covers the full preflight workflow: understand the rules, inspect the market snapshot, and get a decision before placing an order. No obvious dead ends or missing operations are apparent.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Pre-execution governance for AI agents. Deterministic PASS/FAIL/REVIEW verdicts, replayable proof.
Deterministic pre-execution audit for trading agents. PASS/WAIT/FAIL, reproducible verdict_hash.
Advisory policy preflight for AI-agent spend requests; never executes payments or accesses wallets.
Risk preflight for AI Agent tool actions and Polymarket settlement and execution checks.
