# Local MCP server

Source: https://docs.tradefloor.dev/mcp-local.html

> Run tradefloor's MCP server on your machine so an MCP client can build simulated markets, score strategy specs and trade step by step in a session.

`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](https://docs.tradefloor.dev/llm-adapters.html) on your machine. For markets saved between runs, see the [hosted app](https://docs.tradefloor.dev/hosted.html), 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](https://docs.astral.sh/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](https://docs.tradefloor.dev/claude-code.html), [Claude Desktop](https://docs.tradefloor.dev/claude-desktop.html), [Cursor](https://docs.tradefloor.dev/cursor.html) and [VS Code](https://docs.tradefloor.dev/vs-code.html)
- Agent frameworks: [CrewAI](https://docs.tradefloor.dev/crewai.html), [LlamaIndex](https://docs.tradefloor.dev/llamaindex.html), [AutoGen](https://docs.tradefloor.dev/autogen.html), [smolagents](https://docs.tradefloor.dev/smolagents.html), [Google ADK](https://docs.tradefloor.dev/google-adk.html) and [Agno](https://docs.tradefloor.dev/agno.html)

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](https://docs.tradefloor.dev/glossary.html#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](https://docs.tradefloor.dev/populated.html)). 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](https://docs.tradefloor.dev/api-integrations.html#the-mcp-server) 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](https://docs.tradefloor.dev/troubleshooting.html#installation-and-extras).
