Back to Browse

Irl Gateway MCP Server

Developer ToolsUse Caution4.8MCP RegistryLocal
Free

Server data from the Official MCP Registry

An AI agent's trading mandate it can't break: checked before every order, reasoning sealed in IRL.

About

An AI agent's trading mandate it can't break: checked before every order, reasoning sealed in IRL.

Security Report

4.8
Use Caution4.8High Risk

IRL Gateway is a trading MCP server whose main risk is by design: execute_trade places real market orders on exchanges. Its controls are reasonable: IRL policy checks run before any order, the server fails closed, a kill switch exists, and no hardcoded secrets or shell execution appear in the reviewed code. The remaining concerns are low-severity: the token is stored in a plaintext file that depends on OS permissions, the init flow performs automatic remote signup, and the broker source was truncated so it could not be fully reviewed. Supply chain analysis found 5 known vulnerabilities in dependencies (0 critical, 4 high severity). Package verification found 1 issue.

6 files analyzed · 12 issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

HTTP Network Access

Connects to external APIs or services over the internet.

File System Read

Reads files on your machine. Normal for tools that analyze or process local data.

File System Write

Writes or modifies files on your machine. Check that this is expected for the tool.

env_vars

Check that this permission is expected for this type of plugin.

What You'll Need

Set these up before or after installing:

IRL server URL. Optional: by default read from ~/.irl-gateway/agent.json; run `uvx irl-gateway init` to create it (free paper token from https://norve.dev)Optional

Environment variable: IRL_BASE_URL

Bearer token for the IRL server. Optional: by default read from ~/.irl-gateway/agent.json, or run `uvx irl-gateway init`Required

Environment variable: IRL_API_TOKEN

The agent registered on IRL (its mandate). Optional: by default read from ~/.irl-gateway/agent.json, or run `uvx irl-gateway init`Optional

Environment variable: IRL_AGENT_ID

The model hash the agent was registered with (64 hex). Optional: by default read from ~/.irl-gateway/agent.json, or run `uvx irl-gateway init`Optional

Environment variable: IRL_MODEL_HASH

paper (default, live prices, no keys) or exchangeOptional

Environment variable: GATEWAY_BROKER

Starting paper balances, e.g. USDT=1000Optional

Environment variable: PAPER_BALANCES

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "irl-gateway": {
      "command": "uvx",
      "args": [
        "irl-gateway==0.3.1"
      ],
      "env": {
        "IRL_AGENT_ID": "your-irl-agent-id-here",
        "IRL_BASE_URL": "your-irl-base-url-here",
        "IRL_API_TOKEN": "your-irl-api-token-here",
        "GATEWAY_BROKER": "your-gateway-broker-here",
        "IRL_MODEL_HASH": "your-irl-model-hash-here",
        "PAPER_BALANCES": "your-paper-balances-here"
      }
    }
  }
}

Some servers take additional arguments. See the repository for details.

Documentation

View on GitHub

From the project's GitHub README.

IRL Gateway

Give your AI agent a trading account it can't misuse, and a record of every decision it can't rewrite.

IRL Gateway is an MCP server that sits between an AI agent (Claude, ChatGPT, or your own) and an exchange account. Every order the agent places goes through the IRL Engine:

  1. Policy before execution. IRL checks the order against the agent's mandate (active status, notional cap, allowed assets and venues) before anything reaches the exchange. Out of mandate means no order.
  2. The rationale is sealed. The agent must say why it is trading. The gateway hashes that rationale together with the trade inputs and seals the hash into IRL's tamper-evident trace, anchored daily to Bitcoin. The plaintext stays in your local journal.
  3. Intent is reconciled with the fill. After the exchange fills the order, IRL compares what was authorized with what executed and records MATCHED or DIVERGENT.

When something goes wrong, you can prove what the agent was allowed to do, what it said it was doing, and what actually happened.

AI agent ── MCP ──> irl-gateway ──> IRL: authorize (policy + sealed rationale)
                         │
                         ├──────> exchange: market order (client id = sealed intent)
                         │
                         └──────> IRL: bind fill -> MATCHED / DIVERGENT

Tools

ToolWhat it does
execute_trade(symbol, side, rationale, quantity | notional)The only tool that moves money. Spot market order through authorize → place → bind. Returns filled, denied, blocked or failed, with the IRL trace_id and verdict.
get_policy()The agent's mandate as IRL enforces it, plus the local kill-switch state.
get_quote(symbol)Last price on the gateway's venue.
get_balances()Free balances (paper or exchange).
get_trace(trace_id)IRL's sealed record of one trade.
list_recent_trades(limit)Local journal: rationale, context hash, trace id and outcome per trade.

Behaviour the agent can rely on:

  • Fail closed. If IRL is unreachable or denies the intent, no order is sent.
  • Kill switch. Create the file ~/.irl-gateway/KILL and every trade is refused before IRL is even called. Delete it to resume.
  • No silent fills. If the exchange fills but the IRL bind fails, the result still reports the fill and flags it for reconciliation.
  • Sealed = sent. Order sizes are rounded to the venue's step and checked against its minimums before IRL seals them, so the sealed quantity is exactly what reaches the exchange. An order the venue would reject is blocked with a plain reason instead.

Requirements

  • uv, which provides uvx. The commands below and the MCP config that init prints run the gateway through uvx, which also fetches a suitable Python for you. Without uv you get uvx: command not found.
  • Alternatively, pipx install irl-gateway or pip install irl-gateway on Python 3.12 or newer (the python3 that ships with macOS is older). Then run irl-gateway instead of uvx irl-gateway, and in your MCP client use the absolute path of the irl-gateway executable as the command.

Quick start (paper trading, about a minute)

uvx irl-gateway init

That one command gets a free paper-tier token from norve.dev, registers your agent with a starter mandate (BTC/USDT and ETH/USDT, at most 1,000 USDT per order, on paper-binance), saves the credentials to ~/.irl-gateway/agent.json (or $IRL_GATEWAY_HOME, or --home), and prints:

  • a claude mcp add irl-gateway -- uvx irl-gateway line for Claude Code, and
  • an mcpServers block for Claude Desktop, Cursor or any MCP client.

Paste one of them, then ask the agent to call get_policy and make its first paper trade. Paper fills are simulated at live public Binance prices with Binance's real order-size rules, so no exchange keys are needed.

The server reads the token from agent.json, so neither config contains it. In the mcpServers block, command is the absolute path of uvx on your machine: desktop apps such as Claude Desktop on macOS don't inherit your shell's PATH, and a bare "uvx" fails there with spawn uvx ENOENT. init only takes uvx from absolute PATH entries other than the current directory, so a uvx dropped into the folder you run it from never ends up in your config. If it can't find one, it prints "uvx" with a warning; replace it with the output of which uvx (macOS/Linux) or where uvx (Windows).

agent.json holds your token. On macOS and Linux, init creates it with mode 600 (only you can read it). On Windows its access comes from the folder's permissions: inside your user profile (the default) other users can't read it, but with --home or IRL_GATEWAY_HOME pointing outside the profile it may be readable by others, so keep it in a private folder.

Running init again doesn't sign up again: it finds the existing agent.json and prints the config. Use --force to register a new agent. The previous file is kept as agent.json.<timestamp>.bak, and it still holds the old token: delete it, or revoke that token, once you no longer need it.

Options: --name, --assets BTC/USDT,SOL/USDT, --max-notional 250, --contact you@example.com (so we can reach you), --server (your own IRL engine), --home (where to keep agent.json), --force.

Run irl-gateway --help or --version at any time. If the server starts without any configuration, it says so on stderr and tells you to run uvx irl-gateway init.

Free tier limits: paper venues only, up to 3 agents and 500 authorizations a day per token. Want to trade live, or run without limits? Self-host the engine or ask for a full token.

curl -X POST https://norve.dev/irl/signup -H "Content-Type: application/json" -d '{"client_name": "my-claude-trader"}'
# -> {"token": "...", "tier": "paper", ...}  (shown once)

curl -X POST https://norve.dev/irl/agents -H "Authorization: Bearer $IRL_API_TOKEN"   -H "Content-Type: application/json" -d '{
    "name": "my-claude-trader",
    "model_hash_hex": "<sha256 of your agent config>",
    "max_notional": 100,
    "allowed_assets": ["BTC/USDT", "ETH/USDT"],
    "allowed_venues": ["paper-binance"]
  }'

Then add the gateway to your MCP client:

{
  "mcpServers": {
    "irl-gateway": {
      "command": "uvx",
      "args": ["irl-gateway"],
      "env": {
        "IRL_BASE_URL": "https://norve.dev",
        "IRL_API_TOKEN": "…",
        "IRL_AGENT_ID": "<agent_id from registration>",
        "IRL_MODEL_HASH": "<the same model_hash_hex>",
        "AGENT_MODEL_ID": "claude-opus-5-5",
        "PAPER_BALANCES": "USDT=1000"
      }
    }
  }
}

Configuration

VariableDefaultMeaning
IRL_BASE_URL, IRL_API_TOKENfrom agent.jsonIRL server and bearer token
IRL_AGENT_ID, IRL_MODEL_HASHfrom agent.jsonThe registered agent and its model hash
AGENT_MODEL_IDunspecified-modelModel name sealed into each trace (the agent can override it per trade)
AGENT_CONFIG_CHECKSUMnoneOptional checksum of the agent's configuration, sealed into each trace
IRL_L2_MODEoffregime if your IRL server requires Layer 2 regime binding
GATEWAY_BROKERpaperpaper or exchange
EXCHANGE_IDbinanceAny ccxt exchange id; also the price source for paper trading
EXCHANGE_API_KEY, EXCHANGE_API_SECRETRequired for exchange
EXCHANGE_TESTNETtrueUse the exchange's testnet
PAPER_BALANCESUSDT=1000Starting paper balances (used only until paper_state.json exists; the paper account then persists across restarts)
IRL_GATEWAY_HOME~/.irl-gatewayLocation of agent.json, the journal (journal.jsonl), the kill switch (KILL) and the paper account (paper_state.json)

Environment variables take priority over agent.json, and empty values count as unset. The identity (IRL_API_TOKEN, IRL_AGENT_ID, IRL_MODEL_HASH) is never mixed: set all three in the environment, or none of them to use the file. The file's token is only sent to the server it was issued for: if IRL_BASE_URL points elsewhere, the gateway refuses to start. agent.json can't set the broker or exchange keys, so a file on disk never switches the gateway to a live account. On macOS and Linux the gateway refuses an agent.json owned by another user or writable by group or others, and warns if it is readable by them (fix either with chmod 600 ~/.irl-gateway/agent.json).

The venue IRL sees is the exchange id (binance), or paper-<exchange> for paper trading, so a mandate can allow paper trading while denying the real account.

How the rationale is sealed

For each trade the gateway builds a context of the rationale, symbol, side, quantity, reference price, venue, model id and client order id. It hashes that context as canonical JSON (sorted keys, no whitespace) with SHA-256 and sends the hash to IRL as prompt_version = "ctx-sha256:<hex>", which IRL seals into the trace's reasoning_hash.

The journal stores the full context next to its hash, so anyone holding a journal line can recompute the hash and match it to the sealed trace. IRL itself never sees the rationale's text.

Development

python -m venv .venv && .venv/bin/pip install -e ".[dev]"
pytest --cov=irl_gateway
ruff check src tests && black --check src tests && isort --check-only src tests && mypy src

Status

Early (0.1). Spot market orders only. Paper trading and ccxt exchanges are supported; Alpaca is next. Not investment advice, and no strategy is included: the gateway controls and records what your agent does, it does not decide.

MIT licensed.

Reviews

No reviews yet

Be the first to review this server!