AI agents (MCP)

@rivalizer/mcp is a Model Context Protocol server that lets an AI agent control Rivalizer as a user — browse and issue contracts, place and accept trophy wagers (cash + trophies as combined collateral), buy/sell trophies, manage in-app balance, profile, KYC, and stores — all through one scoped API key.

The agent can only do what the key's scopes allow. A key with BALANCE can read and top up the balance but is 403'd on trophy actions, and so on. (See API keys & scopes.)

1. Get a scoped API key

In the Rivalizer web app: account menu (your avatar) → Developer → Create API key, pick a name and the scopes you want the agent to have, and copy the secret (shown once, prefix rk_).

2. Configure the MCP client

Add this to your MCP client config (Claude Desktop, etc.). The server runs via npx, so no install step is needed:

{
  "mcpServers": {
    "rivalizer": {
      "command": "npx",
      "args": ["-y", "@rivalizer/mcp"],
      "env": {
        "RIVALIZER_API_KEY": "rk_your_key_here",
        "RIVALIZER_API_BASE": "https://api.rivalizer.com/v1"
      }
    }
  }
}

• RIVALIZER_API_KEY is required; the server exits if it is unset.
• RIVALIZER_API_BASE is optional and defaults to https://api.rivalizer.com/v1.

The server speaks stdio and forwards each tool call to the REST API with your x-api-key. Each tool returns the API's JSON, or a clear error (e.g. "This API key is missing the 'TROPHIES' scope.").

3. Tools

Scopes gate tools: a tool whose scope your key lacks returns a scope error. Tools marked Public need no scope.

Identity & profile

Tool	Maps to	Scope
whoami	GET /users/me	PROFILE
update_profile	PATCH /users/me	PROFILE
get_kyc	GET /kyc/me	PROFILE
submit_kyc	POST /kyc/submit	PROFILE

Contracts (markets)

Tool	Maps to	Scope
list_contracts	GET /markets	Public
get_contract	GET /markets/:id	Public
contract_capacity	GET /markets/:id/capacity	Public
suggest_odds	POST /markets/suggest-odds	Public
create_contract	POST /markets	MARKETS_WRITE
close_contract	POST /markets/:id/close	MARKETS_WRITE
my_positions	GET /orders	JWT / ORDERS_WRITE key

Trophies

Tool	Maps to	Scope
trophy_store	GET /trophies	Public
my_trophy_case	GET /trophies/me	TROPHIES
buy_trophy	POST /trophies/buy	TROPHIES
sell_trophy	POST /trophies/sell	TROPHIES

Trophy wagers (cash + trophies as combined collateral)

Tool	Maps to	Scope
open_wagers	GET /trophies/wagers	Public
my_wagers	GET /trophies/wagers/me	WAGERS
create_wager	POST /trophies/wagers	WAGERS
accept_wager	POST /trophies/wagers/:id/accept	WAGERS
cancel_wager	POST /trophies/wagers/:id/cancel	WAGERS

In-app balance

Tool	Maps to	Scope
get_balance	GET /balance	BALANCE
balance_transactions	GET /balance/transactions	BALANCE
deposit_balance	POST /balance/deposit	BALANCE

Stores

Tool	Maps to	Scope
list_stores	GET /stores	Public
my_store	GET /stores/me	STORES
create_store	POST /stores	STORES
update_store	PATCH /stores/:id	STORES

4. Run from source (development)

npm install
RIVALIZER_API_KEY=rk_... npm run dev   # run from source
npm run build                          # bundle to dist/ (executable bin)