# coinvest-mcp

A local [MCP](https://modelcontextprotocol.io) server that exposes Liquid
Co-Invest'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 Liquid backend and forwards each call there. All reasoning
happens in your local agent; Liquid executes the individual tool calls.

> **Backend dependency.** This client talks to the Liquid Co-Invest backend
> `mcp_api` endpoints (`GET /api/mcp/tools`, `POST /api/mcp/dispatch`,
> `GET /api/mcp/guide`), which must be deployed and enabled for your user.

## What it exposes

Whatever the backend registry advertises — market data, balances, portfolio
analytics, order status, and trading (spot, perps, prediction markets, and
batch orders, plus cancel / close / 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
`coinvest_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 `coinvest-mcp` entry point:

```bash
uvx --from git+https://github.com/liquid-public/coinvest-mcp.git coinvest-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/liquid-public/coinvest-mcp.git@main coinvest-mcp
```

To install it once as a persistent tool on your `PATH` (so the command is just
`coinvest-mcp`), use `uv tool` instead:

```bash
uv tool install git+https://github.com/liquid-public/coinvest-mcp.git
uv tool upgrade coinvest-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/liquid-public/coinvest-mcp.git coinvest-mcp`.

## Configuration

| Var | Required | Description |
|-----|----------|-------------|
| `COINVEST_URL` | yes | Base URL of the Co-Invest server, e.g. `https://coinvest.liquid.trade` |
| `COINVEST_MCP_TOKEN` | yes | Your MCP token (generate/regenerate it in the Liquid web app) |
| `COINVEST_READONLY` | no | `1` to hide all write/trading tools |
| `COINVEST_TIMEOUT` | no | HTTP timeout in seconds (default 30) |

The token can be generated from the Liquid web app ([app.liquid.trade](https://app.liquid.trade)).

The token authenticates as you; every call is scoped to your account
server-side. One running server == one Liquid user. The token expires after a
period (default 30 days) of inactivity (it is refreshed on each use); once
expired, requests return `401` and you regenerate it from the Liquid web app.

## 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 coinvest \
  --env COINVEST_URL=https://coinvest.liquid.trade \
  --env COINVEST_MCP_TOKEN=your-token-here \
  -- uvx --from git+https://github.com/liquid-public/coinvest-mcp.git coinvest-mcp
```

Add `--env COINVEST_READONLY=1` for a read-only setup.

### Claude Desktop / generic MCP client (JSON)

```json
{
  "mcpServers": {
    "coinvest": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/liquid-public/coinvest-mcp.git",
        "coinvest-mcp"
      ],
      "env": {
        "COINVEST_URL": "https://coinvest.liquid.trade",
        "COINVEST_MCP_TOKEN": "your-token-here"
      }
    }
  }
}
```

For a read-only setup, add `"COINVEST_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/liquid-public/coinvest-mcp.git
cd coinvest-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/coinvest-mcp coinvest-mcp
```

## Safety

The local agent owns risk. Liquid runs no server-side agent for these calls —
there is no automated margin management, invariant enforcement, or liveness
rescue behind them. See the `coinvest_operating_guide` prompt for the operating
contract.