Metadata-Version: 2.4
Name: vordium-mcp
Version: 0.4.1
Summary: Model Context Protocol server for Vordium: market data, accounts and policy-limited agent trading for any MCP client
Author-email: Vordium <dev@vordium.com>
License: MIT
Project-URL: Homepage, https://vordium.com
Project-URL: Documentation, https://docs.vordium.com/build/mcp/
Project-URL: Repository, https://github.com/Vordium/vordium-mcp
Project-URL: Explorer, https://vordscan.io
Keywords: vordium,mcp,model-context-protocol,ai,agents,perps,clob,trading
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: trade
Requires-Dist: vordium>=1.4.5; extra == "trade"
Dynamic: license-file

# Vordium MCP server

Connect any AI that speaks the [Model Context Protocol](https://modelcontextprotocol.io) — Claude, ChatGPT, Cursor, or
your own agent — to [Vordium](https://vordium.com). It can read markets, prices, order books, funding, accounts, agents,
rewards and the explorer, and, once the network switches agent trading on, place and cancel orders as an agent whose
limits the chain enforces.

**No install:** add `https://mcp.vordium.com/testnet/mcp` to your client as a remote MCP server (streamable HTTP, no
account). That server is read-only; [mcp.vordium.com](https://mcp.vordium.com) has the steps for each client. Run this
package on your own machine to trade as an agent.

- **Testnet first.** The server reads the Vordium testnet unless you name the main network. Testnet tokens have no value.
- **Runs on your machine.** It talks to your MCP client over stdio. No account, no API key.
- **Your keys stay with you.** No tool takes a private key or recovery phrase, and the server refuses any argument that
  looks like one. To trade, you point the server at a file holding an *agent* key; it signs on your machine, and only
  the signature leaves it.
- **The chain enforces the limits.** An agent trades under the policy and per-market limits set by its owner on-chain.
  This server only refuses early: while the network reports agent trading off, `place_order` and `cancel_order` are
  refused before anything is signed.
- **Nothing is remembered.** Every value is read from the network when a tool is called. The server also checks that
  the network it reads is the one it was started for, and refuses every tool if not.

## Install

You need Python 3.9 or later. The simplest way to run it is [uv](https://github.com/astral-sh/uv), which fetches and runs
the package in one step:

```bash
uvx vordium-mcp --version
```

Or install it with pipx or pip:

```bash
pipx install vordium-mcp
```

Reading needs nothing beyond the Python standard library. Trading needs the Vordium SDK for signing:
`uvx --from "vordium-mcp[trade]" vordium-mcp` or `pipx install "vordium-mcp[trade]"`.

## Connect your client

### Claude Desktop

Add this to `claude_desktop_config.json` (Settings → Developer → Edit Config), then restart Claude Desktop:

```json
{
  "mcpServers": {
    "vordium": {
      "command": "uvx",
      "args": ["vordium-mcp"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add vordium -- uvx vordium-mcp
```

### Cursor

Add this to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "vordium": {
      "command": "uvx",
      "args": ["vordium-mcp"]
    }
  }
}
```

If you installed with pipx or pip, use `"command": "vordium-mcp"` and `"args": []` instead.

Then ask, for example: *"What does the ETH order book on Vordium look like?"* or *"Is agent trading on?"*

## Tools

| Tool | What it answers |
| --- | --- |
| `get_status` | Whether the network is live: block height, blocks per second, validators agreeing, trading and deposits open |
| `get_network` | Which network this is (checked against the network itself) and what the network vouches for now |
| `get_markets` | Every market with its state, leverage, fees and trading rules |
| `get_fees` | Maker and taker fees, maximum leverage, initial and maintenance margin, liquidation fee |
| `get_oracle` | Oracle and mark prices, for every market or one |
| `get_orderbook` | Bids and asks for one market, best first |
| `get_candles` | Price candles for one market |
| `get_trades` | The latest trades in one market |
| `get_funding` | The funding rate, interval and next settlement for one market, and its past settlements |
| `get_account` | Balances, positions with entry, mark, PnL and liquidation price, and open orders |
| `get_fills` | An account's recent trades with fees and realized PnL |
| `get_balance` | An account's USDC: available to trade, in positions, reserved by orders, unrealized PnL |
| `get_positions` | An account's open positions |
| `get_orders` | An account's resting orders |
| `get_agents` | An owner's agents: status, limits, usage and latest actions |
| `get_policy` | Each agent's policy and market limits as the chain stores them, and whether the network enforces them now |
| `get_risk` | Each agent's usage against its policy |
| `get_tiers` | Agent limits by tier and the referral tier table, where the network serves them |
| `get_season` | The current rewards season: status, budget, rules, participants |
| `get_points` | An address's season points by source, rank, whether it qualifies, VORD estimate |
| `get_leaderboard` | The season's points leaderboard, or the trading leaderboard |
| `get_referrals` | An address's referral code, tier, referred volume and earnings |
| `get_tx` | One EVM transaction by hash, with its explorer link |
| `get_block` | One block by height, with its explorer link |
| `get_address` | An address summary, with its explorer link |
| `place_order` | A market or limit order, signed on your machine with the agent key |
| `cancel_order` | Cancel a resting order, as the agent |

Every result starts with `summary`, one plain sentence, followed by the figures and the units they are in. The server
also offers ready-made prompts (market overview, check an account, season standings, explain a transaction, compare
markets) and resources (the network spec, a fees table, documentation links).

A tool that cannot read the network says so; it never answers from memory. A refusal comes back as a tool error that
names the readings behind it, and says that nothing was signed or sent.

## Trading as an agent

An agent is a key that its owner registers on-chain, gives a session, and limits with a policy. See
[Agents](https://docs.vordium.com/infrastructure/agents/) and [Session keys](https://docs.vordium.com/guides/session-keys/).
The owner's own key never goes into this server.

1. Register the agent and create its session from the owner's wallet.
2. Save the agent's private key in a file only you can read: `chmod 600 ~/.vordium/agent.key`.
3. Start the server with trading allowed:

```json
{
  "mcpServers": {
    "vordium": {
      "command": "uvx",
      "args": ["--from", "vordium-mcp[trade]", "vordium-mcp", "--allow-trading",
               "--owner", "0xYOUR_OWNER_ADDRESS", "--agent-key-file", "~/.vordium/agent.key"]
    }
  }
}
```

Before it signs, the server checks, in this order:

1. The network reports agent trading on (`agent_policy_active`, read live from the network's own answer). If not,
   it refuses at once.
2. You started it with `--allow-trading`, an owner and an agent key file.
3. The key is a registered agent of that owner, not revoked, not expired, with a confirmed session, and is not the
   owner's key.
4. The network reports trading open, and the market is trading.

The chain then applies the agent's policy and limits on every validator. An order this server lets through can still
be refused or dropped by the chain; the server returns the chain's answer unchanged and never reports a fill it did
not see. Read `get_orders` and `get_positions` to see what was applied.

## The main network

The main network is used only when you name it:

```json
"args": ["vordium-mcp", "--network", "mainnet"]
```

Use `--rest` to read from your own node instead of the public one; the server
still checks that the node serves the network you named.

## Read-only over HTTP

`vordium-mcp --http localhost:8770` serves the read tools over streamable HTTP at `/mcp`, for clients that connect to a
URL. It lists no trading tools and takes no key or trading flag. It answers JSON (no event stream), limits each client
to `--rate-per-minute` requests (default 120, `--burst` at once), refuses browser origins unless allowed with
`--allow-origin`, and keeps no request log. Put it behind a proxy for anything beyond your own machine, and pass
`--trust-proxy` there so the limit applies per client. `--hosted` sets it up as a public server behind a proxy: any
origin, 60 requests a minute per connection with bursts of 20 (a connection is the `Mcp-Session-Id` the server gives
at `initialize`; a client that sends none is counted by its address), at most 20 times that per address across its
connections, and every read shared for at least 2 seconds. `/health`
answers the server's counters (calls per tool; no address or argument).

## Settings

| Flag | Default |
| --- | --- |
| `--network testnet\|mainnet` | `testnet` |
| `--rest URL` | the network's public REST base |
| `--allow-trading` | off |
| `--owner 0x…` | none |
| `--agent-key-file PATH` | none |
| `--http HOST:PORT` | off (stdio) |
| `--rate-per-minute N` | 120 (hosted 60) |
| `--burst N` | the per-minute rate (hosted 20) |
| `--allow-origin URL` | none (`*` allows any) |
| `--hosted` | off |

`vordium-mcp --help` lists them, with the environment form of each.

## Develop

```bash
pip install -e ".[trade]" pytest
pytest -q tests                        # no network
# the live testnet test reads the real testnet when switched on; nothing is signed or sent
```

## Links

- Documentation: https://docs.vordium.com/build/mcp/
- Explorer: https://vordscan.io
- Python SDK: https://pypi.org/project/vordium/

MIT licensed.
