Content
# taas-mcp
A local [MCP](https://modelcontextprotocol.io) server that exposes Tread's
trading-data and order tools to a local LLM. It is a **thin, generic proxy**:
it holds no hardcoded tools — on startup it fetches the tool catalog from your
Tread backend and forwards each call there. All reasoning happens in your local
agent; Tread executes the individual tool calls.
> **Backend dependency.** This client talks to the Tread backend `mcp_api`
> endpoints (`GET /api/mcp/tools`, `POST /api/mcp/dispatch`, `GET /api/mcp/guide`),
> which must be deployed and the `MCP` feature flag enabled for your user.
> Design / PRD: Linear project _"MCP Server — Local-LLM Trading Data & Orders"_.
## What it exposes
Whatever the backend registry advertises — market data, balances, portfolio
analytics, order status, and trading (single, market-maker, delta-neutral, and
batch orders, plus cancel / pause / resume / set leverage). Because the catalog
is fetched live, adding or changing a tool on the backend needs no new release
here.
It also exposes the authoritative operating guide as the
`tread_operating_guide` prompt, fetched live from the backend — load it before
driving the tools.
## Install
First install [`uv`](https://docs.astral.sh/uv/) — this is the only prerequisite.
The `uvx` command used below ships with `uv` (it's shorthand for `uv tool run`),
so there is nothing else to install:
```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# or, with Homebrew
brew install uv
```
Then install and run straight from the repo — no clone required. `uvx` fetches
the package from GitHub, builds it in an isolated environment (provisioning a
compatible Python automatically), and runs the `taas-mcp` entry point:
```bash
uvx --from git+https://github.com/tread-labs-public/taas_mcp.git taas-mcp
```
The server speaks MCP over stdio, so it's normally launched by your MCP client
(see [Connect your MCP client](#connect-your-mcp-client)) rather than run
interactively. The command above is the same one you put in the client config.
Pin to a branch or tag by appending `@<ref>`:
```bash
uvx --from git+https://github.com/tread-labs-public/taas_mcp.git@main taas-mcp
```
To install it once as a persistent tool on your `PATH` (so the command is just
`taas-mcp`), use `uv tool` instead:
```bash
uv tool install git+https://github.com/tread-labs-public/taas_mcp.git
uv tool upgrade taas-mcp # pull a newer version later
```
> [!NOTE]
> `uvx` caches the build. After the backend ships changes that only affect this
> client, force a rebuild with
> `uvx --refresh --from git+https://github.com/tread-labs-public/taas_mcp.git taas-mcp`.
## Configuration
| Var | Required | Description |
|-----|----------|-------------|
| `TREAD_URL` | yes | Base URL of the Tread server, e.g. `https://app.tread.fi` |
| `TREAD_MCP_TOKEN` | yes | Your MCP token (generate/regenerate it in the Tread web UI) |
| `TREAD_READONLY` | no | `1` to hide all write/trading tools |
| `TREAD_TIMEOUT` | no | HTTP timeout in seconds (default 30) |
The token can be generated from app.tread.fi by accessing the Settings > Security page
<img width="2506" height="1082" alt="image" src="https://github.com/user-attachments/assets/7f5b6c6c-5409-43ca-9d46-348e0e9f35eb" />
The token authenticates as you; every call is scoped to your account
server-side. One running server == one Tread user. The token expires after a
peiod (default 30 days) of inactivity (it is refreshed on each use); once expired, requests
return `401` and you regenerate it from the Tread web UI.
## Connect your MCP client
Point your MCP client at the same `uvx` command. The client launches the server
on demand and passes configuration through `env`.
### Claude Code (CLI)
```bash
claude mcp add tread \
--env TREAD_URL=https://app.tread.fi \
--env TREAD_MCP_TOKEN=your-token-here \
-- uvx --from git+https://github.com/tread-labs-public/taas_mcp.git taas-mcp
```
Add `--env TREAD_READONLY=1` for a read-only setup.
### Claude Desktop / generic MCP client (JSON)
```json
{
"mcpServers": {
"tread": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/tread-labs-public/taas_mcp.git",
"taas-mcp"
],
"env": {
"TREAD_URL": "https://app.tread.fi",
"TREAD_MCP_TOKEN": "your-token-here"
}
}
}
}
```
For a read-only setup, add `"TREAD_READONLY": "1"` to `env`.
> [!NOTE]
> The client must be able to find `uvx` on its `PATH`. If it can't (common on
> macOS GUI apps), use the absolute path from `which uvx` as `command`, e.g.
> `/opt/homebrew/bin/uvx`.
## Develop
Clone the repo for local development, then sync and test:
```bash
git clone https://github.com/tread-labs-public/taas_mcp.git
cd taas_mcp
uv sync
uv run pytest
```
Run your local checkout directly (point the client at this command to test
changes before pushing):
```bash
uv run --directory /path/to/taas_mcp taas-mcp
```
## Safety
The local agent owns risk. Tread runs no server-side agent for these calls —
there is no automated margin management, invariant enforcement, or liveness
rescue behind them. See the `tread_operating_guide` prompt for the operating
contract.
