@torus-economy/mcp-server

MCP server for Torus — earn TRS tokens for your AI usage across 16 providers and 8 MCP clients. Opt in to earn more by displaying sponsor ads while you work.

Quick Start

Recommended — start from the website. Connect your wallet at torus.cc/ai-gateway and copy your personal setup command:

npx @torus-economy/mcp-server init --token trs_yourtoken

Paste it in a terminal, restart your MCP client, done — no further linking needed.

Or start from the terminal:

npx @torus-economy/mcp-server init

This auto-detects your MCP client and registers the server. Use --client to target a specific client:

npx @torus-economy/mcp-server init --client cursor
npx @torus-economy/mcp-server init --client codex

Restart your client, then ask your AI to run torus_setup — it opens your browser to link your wallet and waits for the connection, so setup completes in that one call (if you don't finish in time, running it again finalizes).

Running from a cloned repo

A fresh clone has no dist/ — build first, then use the local CLI instead of npx:

npm install
npx tsc              # or `npm run build` to also build the VS Code extension
node dist/cli.js init

Pointing at a dev stack: by default the server connects to production https://torus.cc. To use a self-hosted/dev deployment instead, export its URL first (takes precedence over config):

export TORUS_API_URL=<your-dev-stack-url>

How It Works

1. torus_setup — Opens a browser to link your Web3 wallet and issues a proxy token, all in one call (skip this if you used init --token from the website)
2. Pick a tracking mode:
   • torus_key_add — routes your AI provider API key through the Torus proxy (auto-detects provider from key prefix)
   • torus_usage_link — passive tracking: Torus polls your provider's usage API, no proxy routing
   • Claude subscription (Pro/Max, no API key) — statusline tracking via init --statusline or init --chain (see Statusline)
   • OpenAI subscription (Codex CLI, no API key) — automatic session-log tracking (see Codex)
3. Use your AI tool normally — your usage is tracked and rewarded with TRS tokens
4. torus_rewards / torus_leaderboard — Check your earnings and ranking
5. Optional: enable sponsor ads (torus-mcp ads on) to earn extra TRS for ads shown on your statusline, spinner, and VS Code status bar

Supported Clients

Auto-configured (via init)

| Client | Config Path | Key | |--------|------------|-----| | Claude Code | ~/.claude/config.json | mcpServers | | Cursor | .cursor/mcp.json (project) | mcpServers | | Windsurf | ~/.codeium/windsurf/mcp_config.json | mcpServers | | Gemini CLI | ~/.gemini/settings.json | mcpServers | | Antigravity | ~/.gemini/antigravity/mcp_config.json | mcpServers | | OpenCode | opencode.json (project) | mcp | | Zed | ~/.config/zed/settings.json | context_servers | | Codex | ~/.codex/config.toml (root override: CODEX_HOME) | mcp_servers |

Manual configuration

Hermes — Add to hermes.yaml:

mcp_servers:
  torus:
    command: npx
    args: ["@torus-economy/mcp-server", "serve"]

OpenClaw — Register via CLI:

openclaw mcp add torus -- npx @torus-economy/mcp-server serve

Supported Providers

torus_key_add supports 16 AI providers. Nine have auto-detection from key prefix:

| Provider | Key Prefix | Auto-detect | |----------|-----------|-------------| | Anthropic | sk-ant- | Yes | | OpenAI | sk-proj- | Yes | | OpenRouter | sk-or- | Yes | | Groq | gsk_ | Yes | | xAI | xai- | Yes | | Perplexity | pplx- | Yes | | NVIDIA | nvapi- | Yes | | Google Gemini | AIza | Yes | | Fireworks | fw_ | Yes | | DeepSeek | — | Specify provider: "deepseek" | | Mistral | — | Specify provider: "mistral" | | Together | — | Specify provider: "together" | | Venice | — | Specify provider: "venice" | | Zhipu | — | Specify provider: "zhipu" | | Moonshot | — | Specify provider: "moonshot" | | MiniMax | — | Specify provider: "minimax" |

For passive usage tracking without proxy routing, torus_usage_link supports Anthropic, OpenAI, OpenRouter, Venice, and Portkey.

Tools

| Tool | Description | |------|-------------| | torus_setup | Link your wallet via browser | | torus_status | Check connection, token, and provider | | torus_key_add | Add API key for any supported provider | | torus_usage | View AI usage stats (week/month/all) | | torus_usage_link | Link an API key for passive usage tracking (no proxy routing) | | torus_rewards | View TRS rewards summary | | torus_leaderboard | See top users by usage | | torus_disconnect | Revoke token and clear credentials |

Statusline (Claude Code)

This is the tracking path for Claude subscription users (Pro/Max) who have no API key to add — usage is tracked from the statusline data instead of the proxy. init can wire Torus into your Claude Code statusline:

npx @torus-economy/mcp-server init --statusline   # Replace with the Torus statusline (full display + tracking)
npx @torus-economy/mcp-server init --chain        # Keep your statusline, add a silent tracking wrapper

With no flag, init configures the Torus statusline when none exists, and otherwise prints both choices. Re-running init updates an existing Torus statusline to the latest version. torus-mcp uninstall removes it and restores your original statusline.

Codex (OpenAI subscription)

The tracking path for ChatGPT subscription users (Plus/Pro) on OpenAI's Codex CLI — no API key needed. Codex has no statusline hook, so the tracking sidecar watches Codex's session logs (~/.codex/sessions, override the root with CODEX_HOME) and reports usage automatically: per-turn token deltas with cache-aware cost at OpenAI's official per-model rates.

Setup:

1. Link your wallet once — either register the MCP server for Codex (init --client codex) and ask Codex to run torus_setup, or run init + torus_setup from any other supported client (or init --token with a token from the website). The token is shared via ~/.torus/config.json.
2. Make sure the sidecar is running. It starts with torus-mcp serve (i.e. whenever an MCP client launches the server); on Linux, torus-mcp install-service is recommended so tracking runs even when no MCP client is open.
3. Use Codex normally. New sessions are picked up within ~15 seconds and appear in torus_usage, the dashboards, and rewards like any other usage.

Notes:

• Tracking starts from when the sidecar first sees a session — usage from before the sidecar was running is never back-billed (restart-safe by design).
• Your subscription rate-limit windows (5h / weekly used_percent) are exposed locally at http://127.0.0.1:8751/openai-usage.

Sponsor Ads (opt-in)

Earn additional TRS by displaying sponsor ads while you work. Ads are off by default: init asks once (default No), and you can switch anytime:

torus-mcp ads on    # enable ad surfaces + earnings
torus-mcp ads off   # disable all ad surfaces
torus-mcp ads       # show current status

Surfaces:

• Statusline — a sponsor line in the Torus statusline
• Spinner — sponsored verbs in Claude Code's working spinner
• VS Code status bar — via the companion extension: enabling ads offers to install it into detected VS Code-family editors; it shows your TRS rewards plus the current sponsor ad, and clicking opens the sponsor's page

Earnings accrue per completed turn while an ad is actually on screen, are validated server-side against your real usage, and appear alongside usage rewards in torus_rewards. Turns earned before opting out are still credited.

Tracking Sidecar

Usage tracking and ad attribution report to a local HTTP sidecar on 127.0.0.1:8751 (override with TORUS_MCP_PORT). The sidecar also watches Codex CLI session logs for OpenAI subscription tracking. On Linux, install it as a supervised systemd user service:

torus-mcp install-service            # write, enable, and start torus-sidecar.service
torus-mcp install-service --dry-run  # preview the unit file and commands

The service restarts automatically on crashes and starts at login (and at boot, when lingering can be enabled). Re-run the command after updating the package so the service picks up the new build.

CLI Commands

torus-mcp init [options]                 Register MCP server (+ statusline setup, one-time ads prompt)
torus-mcp serve                          Start the MCP server (stdio)
torus-mcp ads on|off                     Opt in/out of sponsor-ad earnings
torus-mcp install-service [--dry-run]    Supervise the tracking sidecar via systemd (Linux)
torus-mcp uninstall [--client <name>]    Remove MCP server + statusline

Init options:

• --client <name> — Target client (auto-detected if omitted)
• --token <token> — Pre-set proxy token during init
• --statusline — Replace your statusline with the Torus display + tracking
• --chain — Keep your statusline, add a silent tracking wrapper
• --dry-run — Preview changes without writing files

Configuration

Credentials are stored in ~/.torus/config.json (mode 0600):

{
  "token": "trs_...",
  "apiKey": "sk-ant-...",
  "provider": "anthropic",
  "baseUrl": "https://torus.cc",
  "adsEnabled": false,
  "adsPrompted": true
}

adsEnabled/adsPrompted record the sponsor-ads opt-in (managed by torus-mcp ads on|off).

The server connects to the Torus API at https://torus.cc by default. Override with baseUrl in the config, or with the TORUS_API_URL environment variable (which takes precedence) for development.

Development

git clone https://github.com/torus-economy/torus-mcp-server.git
cd torus-mcp-server
npm install
npm run build
npm test

Requirements

• Node.js >= 18
• Any MCP-compatible client (see Supported Clients above)

License

MIT