# Suigar MCP — full context

## What it is

Suigar MCP (`@suigar/mcp`) is a local stdio Model Context Protocol server for agent-assisted Suigar transaction workflows on Sui. Suigar is a provably fair, fully on-chain casino on the Sui blockchain, live since 2024, with contracts audited by MoveBit.

The server reads Suigar configuration, describes game metadata, pairs a browser wallet, reads wallet balances and coin objects, builds unsigned base64 transaction bytes for casino bets, dry-runs them through Sui client APIs, and can open explicit browser-wallet approval requests. It can also execute supported game transactions from a funded local session wallet. Paired-wallet signing happens in the user's browser wallet; session-wallet signing uses a dedicated local key stored in the operating-system keychain.

## Install

Install for all detected coding agents:

```bash
npx add-mcp @suigar/mcp --name suigar
```

Add `-y` to skip installer prompts. Restart or reload your MCP client after installation.

Generic JSON config for any MCP client:

{
  "mcpServers": {
    "suigar": {
      "command": "npx",
      "args": ["-y", "@suigar/mcp"]
    }
  }
}

- Claude Code: `claude mcp add suigar -- npx -y @suigar/mcp`, then `/mcp` to confirm.
- Codex CLI: `codex mcp add suigar -- npx -y @suigar/mcp`
- Cursor: add the JSON above to `.cursor/mcp.json`, restart Cursor.
- VS Code and other stdio clients: command `npx`, args `["-y", "@suigar/mcp"]`.
- Agent skill: `npx skills add Suigar-Gaming/agent-skills --skill suigar-mcp` teaches an agent to install, configure, operate and troubleshoot the server.

## Tools (26)

Wallet and session wallet:
- setup_session_wallet — open a local setup page to create, recover, or import a persistent session wallet. Recovery phrases and private-key exports stay local and are not returned through MCP.
- get_session_wallet — read the session wallet address, balances, funding QR code, and paired-wallet funding link.
- fund_session_wallet — open a prefilled browser transfer form to fund the session wallet from the paired wallet.
- suigar_login — open the browser wallet pairing flow.
- suigar_logout — disconnect the paired wallet for a selected network.
- get_connection_status — read paired-wallet connection status.
- get_wallet_balances — list aggregate balances for the paired wallet or an explicit address.
- list_wallet_coins — list paginated individual coin objects for the paired wallet or an explicit address.
- get_execution_status — check the result of a browser approval request.

Read:
- read_config — resolved Suigar config for mainnet or testnet: package ids, registry ids, supported coin metadata, price info object ids.
- read_game_metadata — live game parameters, required inputs, Move targets, type arguments and integration notes for one game flow.
- list_nfts — list the Suigar NFT catalog and matching NFTs owned by one address.
- get_referral_commission — simulate the commission a referrer can claim for one configured coin type.
- get_referral_level_up_usd_rewards — simulate the USD level-up rewards a referrer can claim.

Claim rewards:
- build_referral_commission_claim_transaction — build, dry-run, or inspect an unsigned referral commission claim.
- build_referral_level_up_usd_rewards_claim_transaction — build, dry-run, or inspect an unsigned level-up USD reward claim.

NFT:
- build_nft_v1_mint_transaction — build, dry-run, or inspect an NFT V1 mint transaction for a configured Suigar spec.

Build (single-player, on-chain): build_coinflip_transaction, build_limbo_transaction, build_plinko_transaction, build_soccer_transaction, build_wheel_transaction, build_range_transaction.

PvP Coinflip: build_pvp_coinflip_create_transaction, build_pvp_coinflip_join_transaction, build_pvp_coinflip_cancel_transaction.

Transaction tools support these modes where available:
- read-only: returns the intended Move target, type arguments, required inputs and notes.
- build: returns unsigned transaction bytes as base64 plus a summary.
- dry-run: simulates the unsigned transaction and returns success state, errors, gas deltas, balance changes and decoded events.
- execute: opens paired-wallet approval by default. For supported game tools, `executionWallet: "session"` signs and submits from the funded local session wallet.

Inputs: `owner` accepts raw Sui addresses and SuiNS names (name.sui, sub.name.sui). In session-wallet execution, owner is optional; if supplied, it must match the local session wallet. `stake` and `cashStake` are human currency amounts (stake: 1 means 1 SUI or 1 USDC), converted to base units internally. Partner attribution via top-level `partner`.

Networks: testnet by default; mainnet via the per-tool `network` parameter or `SUIGAR_NETWORK=mainnet`. Package ids, coins and price objects resolve on-chain automatically; env vars are only overrides.

Hosts with MCP Apps support render the Suigar Transaction Inspector UI for game metadata and transaction responses.

## Security model

It can: read config, describe game inputs, pair a browser wallet, read balances and coin objects, build unsigned base64 bytes, dry-run and summarize results, request paired-wallet approval, and execute from a funded local session wallet.
It cannot: see private keys in chat, approve a paired-wallet transaction, spend beyond a funded session wallet, or replace a production wallet policy and confirmation UI.

Do not paste private keys, seed phrases, or signing credentials into an MCP chat. Use session wallets only with limited funds you are willing to delegate to the local MCP process. Keep human review enabled for paired-wallet approval workflows, and treat dry-run results as a simulation rather than a guarantee.

## Common agent workflows

- Natural-language play: "Flip 1 SUI on heads" → read_config → build_coinflip_transaction (dry-run) → user signs in their wallet.
- Wallet-aware sizing: the agent checks balances with get_wallet_balances or list_wallet_coins, sizes stakes, builds and dry-runs through MCP, then asks for approval.
- Session statistics: the agent reads the user's public bet history from Sui and aggregates results; every bet is verifiable on-chain.
- Session-wallet auto-play with guardrails: a loop of build → dry-run → execute from a low-funded session wallet, with stop-loss limits enforced by the agent and bounded by session-wallet funds.
- Multi-MCP workflows: compose with price-feed MCPs, messaging MCPs and schedulers (for example: on a price move, build a plinko bet, notify on Telegram after signing).

The MCP provides the transaction-building blocks; orchestration, balance reads, statistics and loops are the agent's work.

## Games

Coinflip, Limbo, Plinko, Soccer, Wheel, Range (vs the house), and PvP Coinflip (vs other players). Stakes in SUI or USDC.

## Links

- Landing: https://mcp.suigar.com/
- Docs: https://suigar.com/docs/mcp/
- Source: https://github.com/Suigar-Gaming/ts-sdks
- npm: https://www.npmjs.com/package/@suigar/mcp
- Agent skills: https://github.com/Suigar-Gaming/agent-skills
- Casino: https://suigar.com/
- SweetHouse staking: https://house.suigar.com/

Gambling involves financial risk and is for adults (18+). Play responsibly.