# 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.