Skip to the page
INTEGRATIONS/LOCAL MCP SERVER

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:

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

ToolWhat it does
describe_simulatorWhat the simulator is, what it is measured to reproduce and what it cannot do, with every shipped preset and population
check_envelopeWhether a question is inside the validated scope, before anything runs
validate_strategyChecks a strategy spec and returns its fingerprint, without running it
build_universeBuilds a universe: generated, concentrated in some sectors, or written by hand
build_scenarioComposes a scenario and shows what it resolves to
list_scenariosThe shipped scenarios, the constructors and the targets
evaluate_strategiesRuns strategies and the five baselines on one market
rank_strategiesRuns them across seeds, with a paired sign test between each pair
run_stress_scenarioWhat a scenario does to each strategy, against the same market without it
explain_price_moveA price move split into the eleven factors that sum to it
explainThe random draws behind one day for one company
start_job, check_jobSlow work in the background, up to 252 days
open_sessionOpens a market the server keeps between calls and returns its id
session_stepAdvances a session by steps or days, with orders for one agent at the first step
session_stateReads a session without changing it, or lists the open sessions
session_forkCopies a session at its present state into a new one
session_rewindReturns a session to one of its checkpoints
list_contractsThe 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_contractsQuotes 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_chainOne expiry's option chain in a session, by strike, for the index or a listed company
close_sessionCloses 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

LimitValue
Days in a direct call60
Days in a background job252
Decision steps a day1 to 22, and days × steps at most 60 × 6 in a direct call
Names in a universe2 to 120
Strategies in one call8
Seeds in rank_strategies2 to 12, six by default
Background jobs running at once2
Sessions open at once8, forks included
Agents in a session8
Steps in one session_step call360
Days in a session504
Checkpoints a session keeps64, keeping the first and dropping the oldest after it
Idle time before a session closes30 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:

DirectoryListing
Official MCP Registryio.github.simoncoombes/tradefloor
Smitherytradefloor/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.