Local MCP server
tradefloor-mcp is an MCP server that runs on your machine. It gives an MCP client such as Claude Code or Claude Desktop tradefloor's simulation and evaluation tools. A model can use them to build universes and scenarios, score strategies written as data, and explain why a price moved. Most tools build a market for one call and then discard it. The session tools keep a market open between calls, so a model can send orders, read what happened and decide again. All the markets are simulated and nothing reaches a broker.
A session lives in the server's memory and ends when the server stops. To run a model as an agent and score it over many steps, use an LLM adapter on your machine. For markets saved between runs, see the hosted app, which is in beta.
Setup
Install the extra (it adds the mcp package) and register the server with your client. The server speaks MCP over stdio and the client starts it as a subprocess.
pip install "tradefloor[mcp]" claude mcp add tradefloor -- tradefloor-mcp
If you have uv, you can skip the first line. uv fetches the package when the client starts the server:
claude mcp add tradefloor -- uvx --with "tradefloor[mcp]" tradefloor mcp
If your client browses an MCP directory, you can add the server from there with the same command. It's listed in the directories below.
The claude mcp add lines are for Claude Code. Clients that use a JSON config file, such as Claude Desktop, take the same command. The client doesn't start in your shell, so give the full path to tradefloor-mcp in the environment where you installed it:
{
"mcpServers": {
"tradefloor": {
"command": "/path/to/venv/bin/tradefloor-mcp"
}
}
}A first tool call
In the client, ask the model to call describe_simulator and read the result before anything else. It says what the simulator is, what it's measured to reproduce and what it can't do. Strategies are JSON StrategySpec objects, and the server won't take code. Next, validate a spec and score it against the baselines on one market.
Here are those calls from Python, using the MCP client library that the extra installs, to show what a client gets back. The script was tested with mcp 2.3.0.
import asyncio
import json
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
SPEC = {"signal": {"kind": "momentum", "lookback_days": 1.0},
"portfolio": {"top_k": 5, "gross": 1.0}}
async def main():
server = StdioServerParameters(command="tradefloor-mcp")
async with stdio_client(server) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools()
print(len(tools.tools), "tools")
checked = await session.call_tool("validate_strategy", {"spec": SPEC})
print("valid:", json.loads(checked.content[0].text)["ok"])
scored = await session.call_tool(
"evaluate_strategies", {"strategies": {"mom": SPEC}, "days": 5})
result = json.loads(scored.content[0].text)
print("versus buy-and-hold:", result["versus_buy_and_hold"]["mom"])
asyncio.run(main())22 tools valid: True versus buy-and-hold: -29928.74
The strategy lost 29,929 against buy-and-hold on that market, a 5-day run on seed 7. Every result has a caveats list of what it can't show, such as a run too short for the model's validated scope. It also has a provenance block with the version, preset, seed and universe, and a model summarizing the result sees those limits too. One seed is one sample. Use rank_strategies to run the specs across seeds with a paired sign test.
Clients and frameworks
There's a page for each client and agent framework below with setup, a first run and the versions it was tested with:
- MCP clients: Claude Code, Claude Desktop, Cursor and VS Code
- Agent frameworks: CrewAI, LlamaIndex, AutoGen, smolagents, Google ADK and Agno
Some frameworks pin mcp below 2.0, and the server needs 2.0 or later. Their pages start the server in a separate environment with uvx.
The tools
| Tool | What it does |
|---|---|
describe_simulator | What the simulator is, what it is measured to reproduce and what it cannot do, with every shipped preset and population |
check_envelope | Whether a question is inside the validated scope, before anything runs |
validate_strategy | Checks a strategy spec and returns its fingerprint, without running it |
build_universe | Builds a universe: generated, concentrated in some sectors, or written by hand |
build_scenario | Composes a scenario and shows what it resolves to |
list_scenarios | The shipped scenarios, the constructors and the targets |
evaluate_strategies | Runs strategies and the five baselines on one market |
rank_strategies | Runs them across seeds, with a paired sign test between each pair |
run_stress_scenario | What a scenario does to each strategy, against the same market without it |
explain_price_move | A price move split into the eleven factors that sum to it |
explain | The random draws behind one day for one company |
start_job, check_job | Slow work in the background, up to 252 days |
open_session | Opens a market the server keeps between calls and returns its id |
session_step | Advances a session by steps or days, with orders for one agent at the first step |
session_state | Reads a session without changing it, or lists the open sessions |
session_fork | Copies a session at its present state into a new one |
session_rewind | Returns a session to one of its checkpoints |
list_contracts | The contracts a session's market lists: each future's symbol, expiry, multiplier and what it settles on, the price index's level, and each option expiry's strike grid, at-the-money volatility and 25-delta skew |
quote_contracts | Quotes for a session's listed contracts: the bid and ask, the fair value and its carry, the margin a contract asks, and an option's volatility and Greeks |
option_chain | One expiry's option chain in a session, by strike, for the index or a listed company |
close_session | Closes a session and returns its final portfolios and every order sent |
Call a market tool twice with the same arguments and you get the same result. A session does too, if you make the same calls from the same open. A refused call returns "ok": false and an error message the model can act on. The scoring tools build a new market for each call and run the strategies in it under the read-only market view an ordinary agent gets. A strategy can't read fair value or fork the market, except through the oracle signal, whose row is marked uses_hidden_state.
Sessions
open_session builds a market and keeps it in the server's memory under an id. Only session_step trades. It advances the market by steps or days and sends orders for one agent at the first step it runs. An order is a signed share count (positive to buy), {"quantity": q, "limit_price": p} for a limit order that waits in the book, or "cancel" to withdraw the agent's waiting orders on that ticker. The result has the fills, each agent's portfolio, the prices and the largest moves.
A session saves a checkpoint at the open and after each session_step call. session_rewind goes back to one and drops the checkpoints after it. session_fork copies the session so you can try two actions from one state. This script buys 500 shares of AAA, forks the session, sells the shares in the copy, runs both copies five more days and then rewinds the first:
import asyncio
import json
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
async def call(session, tool, arguments):
result = await session.call_tool(tool, arguments)
return json.loads(result.content[0].text)
async def main():
server = StdioServerParameters(command="tradefloor-mcp")
async with stdio_client(server) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
opened = await call(session, "open_session", {"universe_size": 12})
held = opened["session_id"]
# buy 500 AAA at the first step, then copy the market
await call(session, "session_step", {"session_id": held, "orders": {"AAA": 500}})
sold = (await call(session, "session_fork", {"session_id": held}))["session_id"]
await call(session, "session_step", {"session_id": sold, "orders": {"AAA": -500}})
for name, sid in (("held", held), ("sold", sold)):
after = await call(session, "session_step", {"session_id": sid, "days": 5})
me = after["agents"]["me"]
print(f"{name}: day {after['clock']['day']}, AAA {after['market']['prices']['AAA']}, "
f"net worth {me['net_worth']:,.0f}")
rewound = await call(session, "session_rewind", {"session_id": held, "step": 1})
print("rewound to step", rewound["clock"]["step"],
"holding", rewound["agents"]["me"]["positions"]["AAA"]["quantity"])
for sid in (held, sold):
await call(session, "close_session", {"session_id": sid})
asyncio.run(main())held: day 5, AAA 195.1299, net worth 997,280 sold: day 5, AAA 195.1216, net worth 1,000,072 rewound to step 1 holding 500.0
The sale in the fork moved AAA's price too, so the two copies end with slightly different prices for it. With no agents, open_session opens one agent called me that you drive with orders. Pass agents to name up to eight. Set an agent to null to drive it yourself, or to a strategy spec to have it trade by itself each step. They all trade in one market and move each other's prices.
Whoever drives a session can fork and rewind it, so they may have seen its future. Session results say this in their caveats. To score a strategy, use evaluate_strategies or rank_strategies, where the strategy is data and sees only the present. Session ids are random. A session nobody has touched for 30 minutes is closed on the next session call.
Presets and populations
evaluate_strategies, rank_strategies, run_stress_scenario, explain_price_move, explain and open_session take preset, the name of any shipped preset. No tool takes model coefficients. Without preset they run the default, pt-v22, which is the preset the realism checks certify. A result on another preset names it and its fingerprint in provenance, next to certified_preset. A caveat then says the run is outside the certified envelope and quotes that preset's measured record.
evaluate_strategies, run_stress_scenario and open_session also take population, either "standard" or "crowded". It adds background traders that react to each strategy (Populated mode). A populated result names the population and its fingerprint in provenance, and a caveat gives what populated mode was measured to do. rank_strategies refuses a population because its paired sign test needs all the strategies on one market. start_job checks any preset or population in its arguments before the job starts.
import asyncio
import json
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
SPEC = {"signal": {"kind": "momentum", "lookback_days": 1.0},
"portfolio": {"top_k": 5, "gross": 1.0}}
async def call(session, tool, arguments):
result = await session.call_tool(tool, arguments)
return json.loads(result.content[0].text)
async def main():
server = StdioServerParameters(command="tradefloor-mcp")
async with stdio_client(server) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
base = {"strategies": {"mom": SPEC}, "days": 5}
for extra in ({}, {"preset": "pt-v20"}, {"population": "crowded"}):
result = await call(session, "evaluate_strategies", {**base, **extra})
run = result["provenance"]
print(run["model_preset"], run.get("population", "isolated"),
result["versus_buy_and_hold"]["mom"])
refused = await call(session, "rank_strategies",
{"strategies": {"mom": SPEC}, "population": "crowded"})
print("rank_strategies ok:", refused["ok"])
asyncio.run(main())pt-v22 isolated -29928.74 pt-v20 isolated -18690.03 pt-v22 crowded -25194.65 rank_strategies ok: False
The version is under tradefloor_version in provenance. Results from 0.9.1 and earlier also carried it as pretium_version.
Limits
| Limit | Value |
|---|---|
| Days in a direct call | 60 |
| Days in a background job | 252 |
| Decision steps a day | 1 to 22, and days × steps at most 60 × 6 in a direct call |
| Names in a universe | 2 to 120 |
| Strategies in one call | 8 |
Seeds in rank_strategies | 2 to 12, six by default |
| Background jobs running at once | 2 |
| Sessions open at once | 8, forks included |
| Agents in a session | 8 |
Steps in one session_step call | 360 |
| Days in a session | 504 |
| Checkpoints a session keeps | 64, keeping the first and dropping the oldest after it |
| Idle time before a session closes | 30 minutes |
The server refuses a direct call over 60 days. For a longer run, pass the arguments to start_job and poll check_job with the id it returns. Jobs and sessions live in the server process, so restarting the server, or the client that started it, loses them and their results.
MCP directories
tradefloor is listed in these MCP directories:
| Directory | Listing |
|---|---|
| Official MCP Registry | io.github.simoncoombes/tradefloor |
| Smithery | tradefloor/tradefloor |
Reference
LLM adapters and MCP in the reference lists the tools and limits under the module tradefloor.mcp, next to the LLM adapters. For install problems, see Installation and extras.