Quickstart

Try the demo first

The fastest way to see PitBridge is to run the MCP server with no config at all. With nothing in ~/.pitbridge/, pitbridge mcp boots a safe paper demo sandbox: a fake account, all 12 guardrails on, and live execution locked. It has no broker link and cannot place a real order, so it never crashes for want of setup.

$ uvx pitbridge mcp
# no config found: booting a safe paper DEMO sandbox.
# fake account, all 12 guardrails on, live locked.
# your agent can now call get_accounts and get_guardrail_status.

Point any MCP client at it and your agent can immediately call get_accounts and get_guardrail_status to see the tools and the guardrail engine before you configure a single thing. When you are ready to point it at your own NinjaTrader account, do the four-step setup below.

Install, safe by default

PitBridge is a Python package. With uv installed, put it on your PATH, or skip the install and run any command ad-hoc with uvx:

$ uv tool install pitbridge
# or skip the install and run any command with uvx:
$ uvx pitbridge doctor

A fresh install cannot place a live order. The default mode is paper, every guardrail is on, and arm-live refuses because the open core ships no live execution provider. There is no agent tool to change any of that. The security model covers why.

Set up in four steps

Point PitBridge at your own account with four commands. Everything stays in paper mode until you deliberately unlock live.

1. Scaffold the config

pitbridge init writes a starter ~/.pitbridge/config.toml you can edit. It never overwrites an existing file unless you pass --force.

$ uvx pitbridge init
# wrote ~/.pitbridge/config.toml
# already there? overwrite with: uvx pitbridge init --force

2. Edit your config

Open ~/.pitbridge/config.toml and set your NinjaTrader account name and the guardrail values you intend to trade under. This example defines one paper account against NinjaTrader's built-in Sim101; the values are yours to choose, and the engine holds you to them.

[daemon]
bind = "127.0.0.1"
port = 8873
paired_mode = false
pairing_token = "pb_pair_demo"   # generate your own: pitbridge pair new

[accounts.sim]
nt_account = "Sim101"
mode = "paper"        # read_only | paper | live (live needs the Pro plugin + arm-live)
profile = "eval"

[accounts.sim.guardrails]
instruments = ["MES 09-26"]
max_contracts_per_order = 2
daily_loss_halt = 500
trading_window = { tz = "America/New_York", open = "09:30", close = "16:00" }

Orders need somewhere to go: the PitBridge add-on inside NinjaTrader 8 connects out to the daemon on port 8873. Until that link is up and reconciled, every order is refused with LINK_DOWN. That is fail-closed behavior, not a bug: no link, no orders.

3. Run the MCP server, or wire it into your agent

pitbridge mcp is the stdio MCP server your agent attaches to. Run it directly to check it starts, or register it inside the runtime you already use. The sections below cover Claude Code, Claude Desktop, and OpenClaw.

$ uvx pitbridge mcp
# stdio MCP server, reads ~/.pitbridge/config.toml
# custom path? append: --config /path/to/config.toml

4. Verify with doctor

pitbridge doctor runs a read-only self-check and prints a PASS, WARN, or FAIL line per section: config, accounts, guardrails, deny-list, kill switch, live gate, and version. Run it whenever something looks off.

$ uvx pitbridge doctor
# read-only self-check, one line per section:
# config      PASS  ~/.pitbridge/config.toml
# accounts    PASS  1 paper account (sim -> Sim101)
# guardrails  PASS  12 on
# deny-list   PASS  0 instruments blocked
# kill switch PASS  not engaged
# live gate   PASS  locked (no pro plugin)
# version     PASS  pitbridge 0.1.1

Claude Code

1. Register the MCP server (stdio) with one command:

$ claude mcp add pitbridge -- uvx pitbridge mcp
# custom config path? append: --config /path/to/config.toml

2. Check it is connected: claude mcp list.
3. Ask Claude for your guardrail status. It calls get_guardrail_status and reads the limits back to you.
4. Ask it to buy 1 MES on the sim account, then ask it to buy 10. The first fills in paper; the second comes back blocked with MAX_CONTRACTS_PER_ORDER.

Claude sees nine tools: five reads and four order actions. There is deliberately no tool to release the kill switch, arm live, or edit a limit.

Claude Desktop

1. Open claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/).
2. Add the server block:

{
  "mcpServers": {
    "pitbridge": {
      "command": "uvx",
      "args": ["pitbridge", "mcp"]
    }
  }
}

3. Restart Claude Desktop. The pitbridge tools appear in the tools menu.
4. Same test as above: a small order fills in paper, an oversized one is blocked with a reason.

A one-click .mcpb bundle for Claude Desktop, with guardrail settings in the native settings UI, is in progress. Until it ships, the JSON block above is the way in.

OpenClaw

1. OpenClaw attaches MCP servers over stdio. Register uvx pitbridge mcp as a server command in your OpenClaw MCP configuration, the same shape as any other stdio server you run.
2. Restart the agent and list tools. You should see the nine pitbridge tools.
3. Tell your agent the account is paper and let it read get_account_state before anything else.

A packaged pitbridge-trading skill, a thin wrapper over these MCP tools with the security story up front, is in progress. After ClawHavoc, read the source of any trading skill before you run it, this one included: the source repository is being opened up alongside launch.

MCP over HTTP: on the roadmap

Honest status: today PitBridge serves MCP over stdio only. A local streamable HTTP endpoint for MCP-over-HTTP clients such as Hermes is on the roadmap and is not in the current build. Until it ships, two routes work now:

1. Any client that can launch a stdio MCP server: register uvx pitbridge mcp as the server command, the same shape as the Claude Code section above.
2. Custom agents and scripts: use the localhost REST API below. Same guardrail verdicts, same audit log, no MCP client required.

Whatever the transport, the daemon binds to localhost. A non-localhost bind requires paired mode and a pairing token before the daemon will even start.

Plain REST and curl

No MCP client at all? The daemon speaks REST on localhost.

1. Start the daemon: uvx pitbridge run
2. Read your account state:

$ curl -s http://127.0.0.1:8873/v1/account_state

3. Place a paper order that passes the guardrails:

$ curl -s -X POST http://127.0.0.1:8873/v1/place_order \
    -H 'content-type: application/json' \
    -d '{"account":"sim","instrument":"MES 09-26","side":"BUY","qty":2}'
# expect "outcome":"SUBMITTED"

4. Now break a rule on purpose:

$ curl -s -X POST http://127.0.0.1:8873/v1/place_order \
    -H 'content-type: application/json' \
    -d '{"account":"sim","instrument":"MES 09-26","side":"BUY","qty":20}'
# expect "outcome":"BLOCKED", "reason_code":"MAX_CONTRACTS_PER_ORDER"

5. Ask why, and prove the log is intact: pitbridge audit why <order_id>, then pitbridge audit verify.

There is also a WebSocket event feed at ws://127.0.0.1:8873/v1/ws for order, fill, and guardrail events. Example values above are example config, not recommendations.

Troubleshooting with doctor

When an order is refused, a client will not connect, or you just want to confirm the state, pitbridge doctor is the one command to reach for. It is read-only and changes nothing. It reports config, accounts, guardrails, the deny-list, the kill switch, the live gate, and the version, each as PASS, WARN, or FAIL. A FAIL points you straight at the part of the setup to fix; for a single order decision,pitbridge audit why <order_id> explains that specific block.

What to read next

The security model explains modes, pairing tokens, the arm-live ritual, and the kill switch. The guardrails page lists all twelve rules with real decision formats. And when you want live execution, pricing explains exactly what the Pro unlock is.